Initial JDK 11 RFR of JDK-8202385: Annotation to mark serial-related fields and methods

[Roger Riggs]

Hi Joe,

Since Externalizable extends Serializable, should it or its methods be 
mentioned,
either in the list to be marked as @Serial or not to be.

Thanks, Roger


On 5/10/2018 11:55 AM, joe darcy wrote:
> Hello,
>
> Please review the webrev (code below) to address
>
>     JDK-8202385: Annotation to mark serial-related fields and methods
>     http://cr.openjdk.java.net/~darcy/8202385.0/
>
> The proposed java.io.Serial annotation type is intended to be used 
> along with an augmented implementation of javac's "serial" lint check; 
> that work will be done separately as part of JDK-8202056: "Expand 
> serial warning to check for bad overloads of serial-related methods".
>
> Currently, javac's serial lint check looks for serialVersionUID fields 
> to be declared in Serializable classes. However, there are various 
> other structural properties of the declaration of 
> serialization-related fields and methods that could be checked at 
> compile-time. The proposed java.io.Serial annotation type (name 
> subject to change [*]) explicitly marks fields and methods that are 
> intended to be called as part of the Serialization machinery. This 
> marking allows using the wrong name for a method or field to be easily 
> caught; the serialization mechanism will generally silently ignore 
> mis-declared serialization-related fields and methods.
>
> Since the annotation is intended for compile-time checking, the 
> annotation type has has source retention, like the Override annotation 
> type.
>
> Cheers,
>
> -Joe
>
> [*] Unleash the bikes from the bikeshed! On the name and package of 
> the annotation type, since the other serialization types are in the 
> java.io package and the checks are not proposed to be part of the 
> language, this annotation type more appropriately lives in java.io 
> package rather than java.lang. The name "Serial" is consistent with 
> the "@serial" javadoc tag. Other possible names include "Serialize" 
> and "SerialRelated". Another possibility would be to have the 
> annotation type be a nested type in java.io.Serializable.
>
> -=-=-=-=-=-=-
>
> // GPLv2 elided.
>
> package java.io;
>
> import java.lang.annotation.*;
>
> /**
>  * Indicates that a field or method is related to the {@linkplain
>  * Serializable serialization mechanism}. This annotation type is
>  * intended to allow compile-time checking of serialization-related
>  * declarations, analogous to the checking enabled by the {@link
>  * java.lang.Override} annotation type to validate method overriding.
>  *
>  * <p>Specifically, annotations of this type are intended to be
>  * applied to serialization-related methods and fields in classes
>  * declared to be {@code Serializable}. The five serialization-related
>  * methods are:
>  *
>  * <ul>
>  * <li>{@code private void writeObject(java.io.ObjectOutputStream 
> stream) throws IOException}
>  * <li>{@code private void readObject(java.io.ObjectInputStream 
> stream) throws IOException, ClassNotFoundException}
>  * <li>{@code private void readObjectNoData() throws 
> ObjectStreamException}
>  * <li><i>ANY-ACCESS-MODIFIER</i> {@code Object writeReplace() throws 
> ObjectStreamException}
>  * <li><i>ANY-ACCESS-MODIFIER</i> {@code Object readResolve() throws 
> ObjectStreamException}
>  * </ul>
>  *
>  * The two serialization-related fields are:
>  *
>  * <ul>
>  * <li>{@code private static final ObjectStreamField[] 
> serialPersistentFields}
>  * <li>{@code private static final long serialVersionUID}
>  * </ul>
>  *
>  * A compiler can validate that a method or field marked with a
>  * <code>@Serial</code> annotation is one of the defined 
> serialization-related
>  * methods declared in a meaningful context.
>  *
>  * <p>It is a semantic error to apply this annotation to other fields 
> or methods, including:
>  * <ul>
>  * <li>fields or methods in a class that is not {@code Serializable}
>  *
>  * <li>fields or methods of the proper structural declaration, but in
>  * a type where they are ineffectual. For example, {@code enum} types
>  * are defined to have a {@code serialVersionUID} of {@code 0L} so a
>  * {@code serialVersionUID} field declared in an {@code enum} type is
>  * ignored. The five serialization-related methods identified above
>  * are likewise ignored for an {@code enum} type.
>  *
>  * </ul>
>  */
> @Target({ElementType.METHOD, ElementType.FIELD})
> @Retention(RetentionPolicy.SOURCE)
> public @interface Serial {
> }
>