1 /*

     2  * Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package java.io;

    27 

    28 import java.lang.annotation.*;

    29 

    30 /**

    31  * Indicates that an annotated field or method is part of the {@linkplain

    32  * Serializable serialization mechanism} defined by the

    33  * <cite>Java Object Serialization Specification</cite>. This

    34  * annotation type is intended to allow compile-time checking of

    35  * serialization-related declarations, analogous to the checking

    36  * enabled by the {@link java.lang.Override} annotation type to

    37  * validate method overriding. {@code Serializable} classes are encouraged to

    38  * use <code>&#64;Serial</code> annotations to help a compiler catch

    39  * mis-declared serialization-related fields and methods,

    40  * mis-declarations that may otherwise be difficult to detect.

    41  *

    42  * <p>Specifically, annotations of this type should be

    43  * applied to serialization-related methods and fields in classes

    44  * declared to be {@code Serializable}. The five serialization-related

    45  * methods are:

    46  *

    47  * <ul>

    48  * <li>{@code private void writeObject(java.io.ObjectOutputStream stream) throws IOException}

    49  * <li>{@code private void readObject(java.io.ObjectInputStream stream) throws IOException, ClassNotFoundException}

    50  * <li>{@code private void readObjectNoData() throws ObjectStreamException}

    51  * <li><i>ANY-ACCESS-MODIFIER</i> {@code Object writeReplace() throws ObjectStreamException}

    52  * <li><i>ANY-ACCESS-MODIFIER</i> {@code Object readResolve() throws ObjectStreamException}

    53  * </ul>

    54  *

    55  * The two serialization-related fields are:

    56  *

    57  * <ul>

    58  * <li>{@code private static final ObjectStreamField[] serialPersistentFields}

    59  * <li>{@code private static final long serialVersionUID}

    60  * </ul>

    61  *

    62  * Compilers are encouraged to validate that a method or field marked with a

    63  * <code>&#64;Serial</code> annotation is one of the defined serialization-related

    64  * methods or fields declared in a meaningful context and issue a warning

    65  * if that is not the case.

    66  *

    67  * <p>It is a semantic error to apply this annotation to other fields or methods, including:

    68  * <ul>

    69  * <li>fields or methods in a class that is not {@code Serializable}

    70  *

    71  * <li>fields or methods of the proper structural declaration, but in

    72  * a type where they are ineffectual. For example, {@code enum} types

    73  * are defined to have a {@code serialVersionUID} of {@code 0L} so a

    74  * {@code serialVersionUID} field declared in an {@code enum} type is

    75  * ignored. The five serialization-related methods identified above

    76  * are likewise ignored for an {@code enum} type.

    77  *

    78  * <li>in a class that is {@code Externalizable}:

    79  * <ul>

    80  *   <li> method declarations of {@code writeObject}, {@code

    81  *   readObject}, and {@code readObjectNoData}

    82  *

    83  *  <li>a field declaration for {@code serialPersistentFields}

    84  * </ul>

    85  *

    86  * While the {@code Externalizable} interface extends {@code

    87  * Serializable}, the three methods and one field above are

    88  * <em>not</em> used for externalizable classes.

    89  *

    90  * </ul>

    91  *

    92  * Note that serialization mechanism accesses its designated fields

    93  * and methods reflectively and those fields and methods may appear

    94  * otherwise unused in a {@code Serializable} class.

    95  *

    96  * @see Serializable

    97  * @see Externalizable

    98  */

    99 @Target({ElementType.METHOD, ElementType.FIELD})

   100 @Retention(RetentionPolicy.SOURCE)

   101 public @interface Serial {}