title: How to design an immutable value class holding java.lang.String?
body: <h2>Objective</h2>
  <p>Create a class to be used as an immutable list of <strong><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html" rel="noreferrer" title="JDK: java.lang.String">String</a></strong> objects.</p>
  <h2>Approach</h2>
  <p>I have decided to leverage <strong><a href="http://code.google.com/p/guava-libraries/" rel="noreferrer" title="Guava: Google Core Libraries for Java">Google Guava</a></strong>'s <strong><a href="http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/ImmutableList.html" rel="noreferrer" title="Guava: com.google.common.collect.ImmutableList&lt;E&gt;">ImmutableList&lt;E&gt;</a></strong> collection rather than wrapping a simple <strong><a href="http://docs.oracle.com/javase/7/docs/api/java/util/List.html" rel="noreferrer" title="JDK: java.util.List&lt;E&gt;">List&lt;E&gt;</a></strong> with <strong><a href="http://docs.oracle.com/javase/7/docs/api/java/util/Collections.html#unmodifiableList(java.util.List)" rel="noreferrer" title="JDK: java.util.Collections.unmodifiableList(List&lt;? extends T&gt; list)">Collections.unmodifiableList(List&lt;? extends T&gt; list)</a></strong> because I understand this avoids unnecessary concurrency checks on the backing <strong><a href="http://docs.oracle.com/javase/7/docs/api/java/util/List.html" rel="noreferrer" title="JDK: java.util.List&lt;E&gt;">List&lt;E&gt;</a></strong>, which is unaware of being wrapped (source: <a href="http://code.google.com/p/guava-libraries/wiki/ImmutableCollectionsExplained" rel="noreferrer">ImmutableCollectionsExplained</a>).</p>
  <h2>Requirements</h2>
  <ul>
  <li>Class with be a &quot;value-holder&quot; to be used across threads</li>
  <li>No code should be allowed to change the inner values after creation</li>
  </ul>
  <h3>Nice-to-haves</h3>
  <ul>
  <li>The class should implement <strong><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Iterable.html" rel="noreferrer" title="JDK: java.lang.Iterable&lt;E&gt;">Iterable&lt;E&gt;</a></strong> for iteration over the values in the order of creation</li>
  <li>There should be only one class for a given set of <strong><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html" rel="noreferrer" title="JDK: java.lang.String">String</a></strong> s.</li>
  </ul>
  <h2>Attempts</h2>
  <p>Here some attempts at it, although more combinations are possible. Forgive the humourous rendition.</p>
  <h3>Attempt #1 (including usage example)</h3>
  <pre><code>import java.util.List;
  import com.google.common.collect.ImmutableList;
  class BritnetSpearsSpellings implements Iterable&lt;String&gt; {
    public static BritnetSpearsSpellings of(String... spellings) {
      BritnetSpearsSpellings britneySpears = new BritnetSpearsSpellings();
      britneySpears.spellings = ImmutableList.copyOf(spellings);
      return britneySpears;
    }
    private List&lt;String&gt; spellings;
    private BritnetSpearsSpellings() {
    }
    public List&lt;String&gt; getSpellings() {
      return spellings;
    }
  }
  @Override
  public Iterator&lt;String&gt; iterator() {
    return spellings.iterator();
  }
  public class Usage {
    public static void main(String[] args) {
      for (String sepllin : BritnetSpearsSpellings.of(&quot;Brittany Spears&quot;, &quot;Brittney Spears&quot;, &quot;Britany Spears&quot;))
        System.out.printf(&quot;You spel Britni like so: %s%n&quot;, sepllin);
      }
    }
  }
  </code></pre>
  <h3>Attempt #2</h3>
  <pre><code>class BritnetSpearsSpellings implements Iterable&lt;String&gt; {
    public static BritnetSpearsSpellings of(String... spellings) {
      BritnetSpearsSpellings britneySpears = new BritnetSpearsSpellings();
      britneySpears.spellings = ImmutableList.copyOf(spellings);
      return britneySpears;
    }
    private ImmutableList&lt;String&gt; spellings;
    private BritnetSpearsSpellings() {
    }
    public ImmutableList&lt;String&gt; getSpellings() {
      return spellings;
    }
    @Override
    public Iterator&lt;String&gt; iterator() {
      return spellings.iterator();
    }
  }
  </code></pre>
  <h3>Attempt #3</h3>
  <pre><code>class BritnetSpearsSpellings implements Iterable&lt;String&gt; {
    public static BritnetSpearsSpellings of(String... spellings) {
      BritnetSpearsSpellings britneySpears = new BritnetSpearsSpellings(ImmutableList.copyOf(spellings));
      return britneySpears;
    }
    private final ImmutableList&lt;String&gt; spellings;
    private BritnetSpearsSpellings(ImmutableList&lt;String&gt; spellings) {
      this.spellings = spellings;
    }
    public ImmutableList&lt;String&gt; getSpellings() {
      return spellings;
    }
    @Override
    public Iterator&lt;String&gt; iterator() {
      return spellings.iterator();
    }
  }
  </code></pre>
  <h3>Summary of differences</h3>
  <ul>
  <li><h1>1 keeps <strong><a href="http://docs.oracle.com/javase/7/docs/api/java/util/List.html" rel="noreferrer" title="JDK: java.util.List&lt;E&gt;">List&lt;E&gt;</a></strong> in the public interfaces, documenting immutability in the JavaDoc.</h1>
  </li>
  <li><h1>2 stores and exposes everything as <strong><a href="http://code.google.com/p/guava-libraries/" rel="noreferrer" title="Guava: Google Core Libraries for Java">Google Guava</a></strong>'s <strong><a href="http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/collect/ImmutableList.html" rel="noreferrer" title="Guava: com.google.common.collect.ImmutableList&lt;E&gt;">ImmutableList&lt;E&gt;</a></strong></h1>
  </li>
  <li><h1>3 keeps the internal reference as final at the expense of creating a specialised constructor, possibly making the static factory method initialisation look silly in the absence of other initialisation options (which are actually there in the real class)</h1>
  </li>
  </ul>
  <h2>Question</h2>
  <p>Please help me choose among one of these implementations, with your reasoning behind the choice.</p>
  <p>I think the main drawback of approach #2 is that clients need to have cognizance/visibility of the specialised <strong><a href="http://code.google.com/p/guava-libraries/" rel="noreferrer" title="Guava: Google Core Libraries for Java">Google Guava</a></strong> type and probably they shouldn't?</p>