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

[Peter Levart]

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