JDK 14 RF(pre)R: add section on "conditionally serializable" collections

[Stuart Marks]

On 10/3/19 8:32 AM, Joe Darcy wrote:
> In response to the recent and on-going review of serializable types in the base 
> module and elsewhere, I thought it would be helpful if the collections specs 
> discussed how collections were serialiazable. In particular, the proposed 
> terminology is that a collection is "conditionally serializable" if the 
> collection type implements java.io.Serializable and all the elements of the 
> collections are serializable.
> 
> Candidate wording changes to java.util.Collection below. If this notion is 
> deemed useful, I can also go through and add "This collection is conditionally 
> serializable."notes to ArrayList, HashMap, and other such collections.

Hi Joe,

Thanks for doing this. In general I agree that there should be some discussion 
about the serializability of collections. I think it's reasonable to put that 
here (in the Collection interface) which seems to represent the top-level 
documentation for the entire Collections framework, not just that interface. I 
don't think it's necessary to mention conditional serializability in every 
location. However, I think a broader discussion of serializability in the 
collections framework is warranted. Here's some alternative wording:


diff -r 4a98c87dfd89 -r 6aea42e7cb15 
src/java.base/share/classes/java/util/Collection.java
--- a/src/java.base/share/classes/java/util/Collection.java	Thu Oct 03 23:13:28 
2019 -0700
+++ b/src/java.base/share/classes/java/util/Collection.java	Fri Oct 04 16:45:19 
2019 -0700
@@ -188,6 +188,38 @@
   * or if the only reference to the backing collection is through an
   * unmodifiable view, the view can be considered effectively immutable.
   *
+ * <h2><a id="serializable">Serializability of Collections</a></h2>
+ *
+ * <p>Serializability of collections is optional. As such, none of the collections
+ * interfaces are declared to implement the {@link java.io.Serializable} interface.
+ * However, serializability is regarded as being generally useful, so most 
collection
+ * implementations are serializable.
+
+ * <p>The collection implementations that are public classes (such as {@code 
ArrayList}
+ * or {@code HashMap}) are declared to implement the {@code Serializable} 
interface if they
+ * are in fact serializable. Some collections implementations are not public 
classes,
+ * such as the <a href="unmodifiable">unmodifiable collections.</a> In such 
cases, the
+ * serializability of such collections is described in the specification of the 
method
+ * that creates them, or in some other suitable place. In cases where the 
serializability
+ * of a collection is not specified, there is no guarantee about the 
serializability of such
+ * collections. In particular, many <a href="view">view collections</a> are not 
serializable.
+ *
+ * <p>A collection implementation that implements the {@code Serializable} 
interface cannot
+ * be guaranteed to be serializable. The reason is that in general, collections
+ * contain elements of other types, and it is not possible to determine statically
+ * whether instances the element type are actually serializable. For example, 
consider
+ * a serializable {@code Collection<E>}, where {@code E} does not implement the
+ * {@code Serializable} interface. The collection may be serializable, if it 
contains only
+ * elements of some serializable subtype of {@code E}, or if it is empty. 
Collections are
+ * thus said to be <i>conditionally serializable,</i> as the serializability of 
the collection
+ * as a whole depends on whether the collection itself is serializable and on 
whether all
+ * contained elements are also serializable.
+ *
+ * <p>An additional case occurs with instances of {@link SortedSet} and {@link 
SortedMap}.
+ * These collections can be created with a {@link Comparator} that imposes an 
ordering on
+ * the set elements or map keys. Such a collection is serializable only if the 
provided
+ * {@code Comparator} is also serializable.
+ *
   * <p>This interface is a member of the
   * <a 
href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
   * Java Collections Framework</a>.



s'marks