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 are ignored for record types.<p>
147 *
148 * The serialization runtime associates with each serializable class a version
149 * number, called a serialVersionUID, which is used during deserialization to
150 * verify that the sender and receiver of a serialized object have loaded
151 * classes for that object that are compatible with respect to serialization.
152 * If the receiver has loaded a class for the object that has a different
153 * serialVersionUID than that of the corresponding sender's class, then
154 * deserialization will result in an {@link InvalidClassException}. A
155 * serializable class can declare its own serialVersionUID explicitly by
156 * declaring a field named {@code "serialVersionUID"} that must be static,
157 * final, and of type {@code long}:
158 *
159 * <PRE>
160 * ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L;
161 * </PRE>
162 *
163 * If a serializable class does not explicitly declare a serialVersionUID, then
164 * the serialization runtime will calculate a default serialVersionUID value
165 * for that class based on various aspects of the class, as described in the
166 * <a href="{@docRoot}/../specs/serialization/index.html"><cite>Java Object Serialization
|
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>
39 * <p>
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.
45 * <p>
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.
59 * <p>
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.
64 * <p>
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 * 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 * <p>
88 * 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 * <p>
100 * 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 * <p>
111 * 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>
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.
124 * <p>
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>
132 *
133 * This readResolve method follows the same invocation rules and
134 * accessibility rules as writeReplace.
135 * <p>
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.
141 * <p>
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.
148 *
149 * <div class="preview-block">
150 * <div class="preview-comment">
151 * <p>{@linkplain Class#isValue Value classes} that are not records can
152 * implement {@code Serializable}, but cannot be serialized directly. Instead,
153 * the {@code writeReplace} method should be used to designate an alternative
154 * object for serialization. At deserialization time, the alternative object
155 * can implement {@code readResolve} to construct the expected value class
156 * instance.
157 * </div>
158 * </div>
159 *
160 * The serialization runtime associates with each serializable class a version
161 * number, called a serialVersionUID, which is used during deserialization to
162 * verify that the sender and receiver of a serialized object have loaded
163 * classes for that object that are compatible with respect to serialization.
164 * If the receiver has loaded a class for the object that has a different
165 * serialVersionUID than that of the corresponding sender's class, then
166 * deserialization will result in an {@link InvalidClassException}. A
167 * serializable class can declare its own serialVersionUID explicitly by
168 * declaring a field named {@code "serialVersionUID"} that must be static,
169 * final, and of type {@code long}:
170 *
171 * <PRE>
172 * ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L;
173 * </PRE>
174 *
175 * If a serializable class does not explicitly declare a serialVersionUID, then
176 * the serialization runtime will calculate a default serialVersionUID value
177 * for that class based on various aspects of the class, as described in the
178 * <a href="{@docRoot}/../specs/serialization/index.html"><cite>Java Object Serialization
|