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

[David Lloyd]

Would it be allowed to enable the serial lint without using the
@Serial annotation?

On Thu, May 10, 2018 at 10:55 AM, joe darcy <joe.darcy at oracle.com> 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 {
> }
>



-- 
- DML