Question

I am trying to determine what the best practices would be for an ImmutableList. Below is a simplistic example that will help drive my questions:

Ex:

public ImmutableCollection<Foo> getFooOne(ImmutableList<Foo> fooInput){ 
   //.. do some work
   ImmutableList<Foo> fooOther = // something generated during the code
   return fooOther;
}

public Collection<Foo> getFooTwo(List<Foo> fooInput){
   //.. do some work
   List<Foo> fooOther = // something generated during the code
   return ImmutableList.copyOf(fooOther);
}

public void doSomethingOne(){
  ImmutableCollection<Foo> myFoo = getFooOne(myList);
  ...
  someOtherMethod(myFoo);
}

public void doSomethingTwo(){
  Collection<Foo> myFoo = getFooOne(myList);
  ...
  someOtherMethod(myFoo);
}

My Questions:

1. Which makes the most sense to use in an application? [doSomethingOne and getFooOne] or [doSomethingTwo and fooTwo]? In other words if you know you are using ImmutableCollections does it make sense to keep casting back and forth and doing copyOf(), or just use Immutable everywhere?

2. These examples are public methods which could imply that other people use them. Would any of these answers change if the methods were private and used internally?

3. If a user tries to add anything to an immutable List an exception will be thrown. Because they may not be aware of this, wouldn’t it make more sense to explicitly return an ImmutableCollection instead of a Collection?

Answer 1

In general, it’s wise not to commit to a specific implementation in your declared return type, but we think of the immutable types as an exception. There are a few reasons to declare a return type of Immutable*:

• They document that you’re returning a snapshot, not a live view.
• They document that the caller can’t mutate the result.
• They document that insertion order is preserved (which may or may not be significant in your use case).
• They document that the collection won’t contain null.
• Someone might want the asList() or reverse() method.
• You may save someone a copyOf() call if he wishes to assign to an Immutable* field. (But note that, if he does include copyOf(), it will short-circuit for most immutable inputs, even if you don’t declare the return type.)

Basically, I’m just cribbing from https://github.com/google/guava/wiki/TenThingsAboutImmutableCollections, which you may want to check out in its entirety.