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

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.

[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.

[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.