Guava: Mention the benefits that immutable collections have over Java9's "Convenience Factory Methods for Collections" feature

[ineuwirth]

Java 9 has just introduced the "Convenience Factory Methods for Collections" feature. As ImmutableList.of() and similar methods in Guava, these factory methods create unmodifiable collections and prohibit null elements. The created collections are serializable if all of their elements are serializable.
Please find more details on http://openjdk.java.net/jeps/269.

It's worth considering to extend the Javadoc of the corresponding Guava classes (ImmutableList, ImmutableMap and ImmutableSet) like it happened in 3afc6e45c39504ece02d14f4a462f65acfa98652 to discourage using the old factory methods in favor of the Java 7 diamond syntax.

[ooxi]

The reason I'm using ImmutableList et.al. in favour of Collections.unmodifiableCollection is the semantic type in my API. It's clear that I return an immutable type. Whereas returning just Collection will confuse callers with runtime exceptions.

[jbduncan]

To add to @ooxi's comment, I'd also argue that using Immutable* consistently prevents unnecessary copying when using Immutable*.copyOf([...]) a lot for defensive programming reasons.

[kluever]

+1 to @ooxi 's comment. It's possible that we may want to mention the new convenience factory methods, but we won't discourage the use of ImmutableList, etc.

[ineuwirth]

Thank you all for sharing your points on this. All of them are completely reasonable.

But in that case I am wondering if it could be possible to extend the Javadoc or https://github.com/google/guava/wiki/ImmutableCollectionsExplained Wiki page to highlight why Java 9 folks should still prefer the immutable collections provided by Guava instead of using the new ones in JDK.

[kluever]

Yes, I think that is a good idea.

[kevinb9n]

What about this appended to the "types, not implementations" section?

Expressing the immutability guarantee directly in the type that your code references is a
powerful advantage. Although Java 9 offers certain immutable collection factory methods, like
{@code Set.of},
we continue to prefer use of our immutable collection classes for this reason.

[ineuwirth]

Closed in 4f794799aa981eba0000b54004257c0f4fa78b88