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

[Joe Darcy]

Hello,

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.

Thoughts?

Thanks,

-Joe


--- a/src/java.base/share/classes/java/util/Collection.java Tue Oct 01 
20:07:30 2019 -0700
+++ b/src/java.base/share/classes/java/util/Collection.java    Wed Oct 
02 22:58:04 2019 -0700
@@ -188,6 +188,17 @@
   * or if the only reference to the backing collection is through an
   * unmodifiable view, the view can be considered effectively immutable.
   *
+ * <h2><a id="condserial">Serializable Collections</a></h2>
+ *
+ * Many collection types implement {@link
+ * java.io.Serializable}. Typically such collections are
+ * <i>conditionally serializable</i>, if all the objects in the
+ * collection are serializable, the collection as a whole can be
+ * serialized. Otherwise, is one or more objects in a collection are
+ * <em>not<em> serializable, the collection cannot be serialized and a
+ * {@link java.io.NotSerializableException} may be thrown on attempts
+ * to serialize such a collection.
+ *
   * <p>This interface is a member of the
   * <a 
href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
   * Java Collections Framework</a>.