Question

Objective

Create a class to be used as an immutable list of String objects.

Approach

I have decided to leverage Google Guava‘s ImmutableList<E> collection rather than wrapping a simple List<E> with Collections.unmodifiableList(List<? extends T> list) because I understand this avoids unnecessary concurrency checks on the backing List<E>, which is unaware of being wrapped (source: ImmutableCollectionsExplained).

Requirements

• Class with be a "value-holder" to be used across threads
• No code should be allowed to change the inner values after creation

Nice-to-haves

• The class should implement Iterable<E> for iteration over the values in the order of creation
• There should be only one class for a given set of String s.

Attempts

Here some attempts at it, although more combinations are possible. Forgive the humourous rendition.

Attempt #1 (including usage example)

import java.util.List;
import com.google.common.collect.ImmutableList;
class BritnetSpearsSpellings implements Iterable<String> {
  public static BritnetSpearsSpellings of(String... spellings) {
    BritnetSpearsSpellings britneySpears = new BritnetSpearsSpellings();
    britneySpears.spellings = ImmutableList.copyOf(spellings);
    return britneySpears;
  }
  private List<String> spellings;
  private BritnetSpearsSpellings() {
  }
  public List<String> getSpellings() {
    return spellings;
  }
}
@Override
public Iterator<String> iterator() {
  return spellings.iterator();
}
public class Usage {
  public static void main(String[] args) {
    for (String sepllin : BritnetSpearsSpellings.of("Brittany Spears", "Brittney Spears", "Britany Spears"))
      System.out.printf("You spel Britni like so: %s%n", sepllin);
    }
  }
}

Attempt #2

class BritnetSpearsSpellings implements Iterable<String> {
  public static BritnetSpearsSpellings of(String... spellings) {
    BritnetSpearsSpellings britneySpears = new BritnetSpearsSpellings();
    britneySpears.spellings = ImmutableList.copyOf(spellings);
    return britneySpears;
  }
  private ImmutableList<String> spellings;
  private BritnetSpearsSpellings() {
  }
  public ImmutableList<String> getSpellings() {
    return spellings;
  }
  @Override
  public Iterator<String> iterator() {
    return spellings.iterator();
  }
}

Attempt #3

class BritnetSpearsSpellings implements Iterable<String> {
  public static BritnetSpearsSpellings of(String... spellings) {
    BritnetSpearsSpellings britneySpears = new BritnetSpearsSpellings(ImmutableList.copyOf(spellings));
    return britneySpears;
  }
  private final ImmutableList<String> spellings;
  private BritnetSpearsSpellings(ImmutableList<String> spellings) {
    this.spellings = spellings;
  }
  public ImmutableList<String> getSpellings() {
    return spellings;
  }
  @Override
  public Iterator<String> iterator() {
    return spellings.iterator();
  }
}

Summary of differences

• 1 keeps List<E> in the public interfaces, documenting immutability in the JavaDoc.

• 2 stores and exposes everything as Google Guava‘s ImmutableList<E>

• 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)

Question

Please help me choose among one of these implementations, with your reasoning behind the choice.

I think the main drawback of approach #2 is that clients need to have cognizance/visibility of the specialised Google Guava type and probably they shouldn’t?

Answer 1

Clearly, #3 is the best choice in my opinion. final enforces and documents the immutability of (that field of) the class, not only the fact that the List itself is immutable.

Whether you expose a List with some javadoc or an actual ImmutableList in the getter is another thing. I’ve seen opinions that returning an ImmutableList documents clearly the intention, but still, you’re then tying yourself to an implementation instead of an interface for something that’s low level and could need to change in the future (even if immutability is “generally” good). So it’s more a global design choice for your application than for just one use case. If you do use ImmutableList, I don’t think that’s a real problem for the clients, the name is explicit and it can easily be seen through your IDE that it’s an implementation of List, and they can access the javadoc if they want more information. And who knows, they might like it and start using it also, with all the other goodies Guava provides 🙂