1 /*
2 * Copyright (c) 1996, 2020, 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 /**
29 * Serializability of a class is enabled by the class implementing the
30 * java.io.Serializable interface.
31 *
32 * <p><strong>Warning: Deserialization of untrusted data is inherently dangerous
33 * and should be avoided. Untrusted data should be carefully validated according to the
34 * "Serialization and Deserialization" section of the
35 * {@extLink secure_coding_guidelines_javase Secure Coding Guidelines for Java SE}.
36 * {@extLink serialization_filter_guide Serialization Filtering} describes best
37 * practices for defensive use of serial filters.
38 * </strong></p>
39 *
40 * Classes that do not implement this
41 * interface will not have any of their state serialized or
42 * deserialized. All subtypes of a serializable class are themselves
43 * serializable. The serialization interface has no methods or fields
44 * and serves only to identify the semantics of being serializable. <p>
45 *
46 * It is possible for subtypes of non-serializable classes to be serialized
47 * and deserialized. During serialization, no data will be written for the
48 * fields of non-serializable superclasses. During deserialization, the fields of non-serializable
49 * superclasses will be initialized using the no-arg constructor of the first (bottommost)
50 * non-serializable superclass. This constructor must be accessible to the subclass that is being
51 * deserialized. It is an error to declare a class Serializable if this is not
52 * the case; the error will be detected at runtime. A serializable subtype may
53 * assume responsibility for saving and restoring the state of a non-serializable
54 * supertype's public, protected, and (if accessible) package-access fields. See
55 * the <a href="{@docRoot}/../specs/serialization/input.html#the-objectinputstream-class">
56 * <cite>Java Object Serialization Specification,</cite></a> section 3.1, for
57 * a detailed specification of the deserialization process, including handling of
58 * serializable and non-serializable classes. <p>
59 *
60 * When traversing a graph, an object may be encountered that does not
61 * support the Serializable interface. In this case the
62 * NotSerializableException will be thrown and will identify the class
63 * of the non-serializable object. <p>
64 *
65 * Classes that require special handling during the serialization and
66 * deserialization process must implement special methods with these exact
67 * signatures:
68 *
69 * <PRE>
70 * private void writeObject(java.io.ObjectOutputStream out)
71 * throws IOException
72 * private void readObject(java.io.ObjectInputStream in)
73 * throws IOException, ClassNotFoundException;
74 * private void readObjectNoData()
75 * throws ObjectStreamException;
76 * </PRE>
77 *
78 * <p>The writeObject method is responsible for writing the state of the
79 * object for its particular class so that the corresponding
80 * readObject method can restore it. The default mechanism for saving
81 * the Object's fields can be invoked by calling
82 * out.defaultWriteObject. The method does not need to concern
83 * itself with the state belonging to its superclasses or subclasses.
84 * State is saved by writing the individual fields to the
85 * ObjectOutputStream using the writeObject method or by using the
86 * methods for primitive data types supported by DataOutput.
87 *
88 * <p>The readObject method is responsible for reading from the stream and
89 * restoring the classes fields. It may call in.defaultReadObject to invoke
90 * the default mechanism for restoring the object's non-static and
91 * non-transient fields. The defaultReadObject method uses information in
92 * the stream to assign the fields of the object saved in the stream with the
93 * correspondingly named fields in the current object. This handles the case
94 * when the class has evolved to add new fields. The method does not need to
95 * concern itself with the state belonging to its superclasses or subclasses.
96 * State is restored by reading data from the ObjectInputStream for
97 * the individual fields and making assignments to the appropriate fields
98 * of the object. Reading primitive data types is supported by DataInput.
99 *
100 * <p>The readObjectNoData method is responsible for initializing the state of
101 * the object for its particular class in the event that the serialization
102 * stream does not list the given class as a superclass of the object being
103 * deserialized. This may occur in cases where the receiving party uses a
104 * different version of the deserialized instance's class than the sending
105 * party, and the receiver's version extends classes that are not extended by
106 * the sender's version. This may also occur if the serialization stream has
107 * been tampered; hence, readObjectNoData is useful for initializing
108 * deserialized objects properly despite a "hostile" or incomplete source
109 * stream.
110 *
111 * <p>Serializable classes that need to designate an alternative object to be
112 * used when writing an object to the stream should implement this
113 * special method with the exact signature:
114 *
115 * <PRE>
116 * ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException;
117 * </PRE><p>
118 *
119 * This writeReplace method is invoked by serialization if the method
120 * exists and it would be accessible from a method defined within the
121 * class of the object being serialized. Thus, the method can have private,
122 * protected and package-private access. Subclass access to this method
123 * follows java accessibility rules. <p>
124 *
125 * Classes that need to designate a replacement when an instance of it
126 * is read from the stream should implement this special method with the
127 * exact signature.
128 *
129 * <PRE>
130 * ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException;
131 * </PRE><p>
132 *
133 * This readResolve method follows the same invocation rules and
134 * accessibility rules as writeReplace.<p>
135 *
136 * Enum types are all serializable and receive treatment defined by
137 * the <a href="{@docRoot}/../specs/serialization/index.html"><cite>
138 * Java Object Serialization Specification</cite></a> during
139 * serialization and deserialization. Any declarations of the special
140 * handling methods discussed above are ignored for enum types.<p>
141 *
142 * Record classes can implement {@code Serializable} and receive treatment defined
143 * by the <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records">
144 * <cite>Java Object Serialization Specification,</cite> Section 1.13,
145 * "Serialization of Records"</a>. Any declarations of the special
146 * handling methods discussed above, except {@code writeReplace},
147 * are ignored for record types.<p>
148 *
149 * Value classes can implement {@code Serializble} and receive the treatment defined
150 * by the <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-value-objects">
151 * <cite>Java Object Serialization Specification,</cite> Section 1.14,
152 * "Serialization of Value Objects"</a>. Any declarations of the special
153 * handling methods discussed above, except {@code writeReplace},
154 * are ignored for value classes. Value classes implementing {@link Externalizable}
155 * and not using {@code writeReplace} are not supported.<p>
156 *
157 * The serialization runtime associates with each serializable class a version
158 * number, called a serialVersionUID, which is used during deserialization to
159 * verify that the sender and receiver of a serialized object have loaded
160 * classes for that object that are compatible with respect to serialization.
161 * If the receiver has loaded a class for the object that has a different
162 * serialVersionUID than that of the corresponding sender's class, then
163 * deserialization will result in an {@link InvalidClassException}. A
164 * serializable class can declare its own serialVersionUID explicitly by
165 * declaring a field named {@code "serialVersionUID"} that must be static,
166 * final, and of type {@code long}:
167 *
168 * <PRE>
169 * ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L;
170 * </PRE>
171 *
172 * If a serializable class does not explicitly declare a serialVersionUID, then
173 * the serialization runtime will calculate a default serialVersionUID value
174 * for that class based on various aspects of the class, as described in the
175 * <a href="{@docRoot}/../specs/serialization/index.html"><cite>Java Object Serialization
176 * Specification.</cite></a> This specification defines the
177 * serialVersionUID of an enum type to be 0L. However, it is <em>strongly
178 * recommended</em> that all serializable classes other than enum types explicitly declare
179 * serialVersionUID values, since the default serialVersionUID computation is
180 * highly sensitive to class details that may vary depending on compiler
181 * implementations, and can thus result in unexpected
182 * {@code InvalidClassException}s during deserialization. Therefore, to
183 * guarantee a consistent serialVersionUID value across different java compiler
184 * implementations, a serializable class must declare an explicit
185 * serialVersionUID value. It is also strongly advised that explicit
186 * serialVersionUID declarations use the {@code private} modifier where
187 * possible, since such declarations apply only to the immediately declaring
188 * class--serialVersionUID fields are not useful as inherited members. Array
189 * classes cannot declare an explicit serialVersionUID, so they always have
190 * the default computed value, but the requirement for matching
191 * serialVersionUID values is waived for array classes.
192 *
193 * @spec serialization/index.html Java Object Serialization Specification
194 * @see java.io.ObjectOutputStream
195 * @see java.io.ObjectInputStream
196 * @see java.io.ObjectOutput
197 * @see java.io.ObjectInput
198 * @see java.io.Externalizable
199 * @since 1.1
200 */
201 public interface Serializable {
202 }