Hi Stuart,
I also prefer your wording. There's just a nit...
On 10/5/19 1:46 AM, Stuart Marks wrote:
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
... whether instances *of* the element type(s) are actually ...
(there are two element types in the Map<K, V>)
+ * 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
Regards, Peter
