< prev index next > src/java.base/share/classes/java/io/Serializable.java
Print this page
* and should be avoided. Untrusted data should be carefully validated according to the
* "Serialization and Deserialization" section of the
* {@extLink secure_coding_guidelines_javase Secure Coding Guidelines for Java SE}.
* {@extLink serialization_filter_guide Serialization Filtering} describes best
* practices for defensive use of serial filters.
! * </strong></p>
! *
* Classes that do not implement this
* interface will not have any of their state serialized or
* deserialized. All subtypes of a serializable class are themselves
* serializable. The serialization interface has no methods or fields
! * and serves only to identify the semantics of being serializable. <p>
! *
* It is possible for subtypes of non-serializable classes to be serialized
* and deserialized. During serialization, no data will be written for the
* fields of non-serializable superclasses. During deserialization, the fields of non-serializable
* superclasses will be initialized using the no-arg constructor of the first (bottommost)
* non-serializable superclass. This constructor must be accessible to the subclass that is being
* and should be avoided. Untrusted data should be carefully validated according to the
* "Serialization and Deserialization" section of the
* {@extLink secure_coding_guidelines_javase Secure Coding Guidelines for Java SE}.
* {@extLink serialization_filter_guide Serialization Filtering} describes best
* practices for defensive use of serial filters.
! * </strong>
! * <p>
* Classes that do not implement this
* interface will not have any of their state serialized or
* deserialized. All subtypes of a serializable class are themselves
* serializable. The serialization interface has no methods or fields
! * and serves only to identify the semantics of being serializable.
! * <p>
* It is possible for subtypes of non-serializable classes to be serialized
* and deserialized. During serialization, no data will be written for the
* fields of non-serializable superclasses. During deserialization, the fields of non-serializable
* superclasses will be initialized using the no-arg constructor of the first (bottommost)
* non-serializable superclass. This constructor must be accessible to the subclass that is being
* assume responsibility for saving and restoring the state of a non-serializable
* supertype's public, protected, and (if accessible) package-access fields. See
* the <a href="{@docRoot}/../specs/serialization/input.html#the-objectinputstream-class">
* <cite>Java Object Serialization Specification,</cite></a> section 3.1, for
* a detailed specification of the deserialization process, including handling of
! * serializable and non-serializable classes. <p>
! *
* When traversing a graph, an object may be encountered that does not
* support the Serializable interface. In this case the
* NotSerializableException will be thrown and will identify the class
! * of the non-serializable object. <p>
! *
* Classes that require special handling during the serialization and
* deserialization process must implement special methods with these exact
* signatures:
*
* <PRE>
* assume responsibility for saving and restoring the state of a non-serializable
* supertype's public, protected, and (if accessible) package-access fields. See
* the <a href="{@docRoot}/../specs/serialization/input.html#the-objectinputstream-class">
* <cite>Java Object Serialization Specification,</cite></a> section 3.1, for
* a detailed specification of the deserialization process, including handling of
! * serializable and non-serializable classes.
! * <p>
* When traversing a graph, an object may be encountered that does not
* support the Serializable interface. In this case the
* NotSerializableException will be thrown and will identify the class
! * of the non-serializable object.
! * <p>
* Classes that require special handling during the serialization and
* deserialization process must implement special methods with these exact
* signatures:
*
* <PRE>
* throws IOException, ClassNotFoundException;
* private void readObjectNoData()
* throws ObjectStreamException;
* </PRE>
*
! * <p>The writeObject method is responsible for writing the state of the
* object for its particular class so that the corresponding
* readObject method can restore it. The default mechanism for saving
* the Object's fields can be invoked by calling
* out.defaultWriteObject. The method does not need to concern
* itself with the state belonging to its superclasses or subclasses.
* State is saved by writing the individual fields to the
* ObjectOutputStream using the writeObject method or by using the
* methods for primitive data types supported by DataOutput.
! *
! * <p>The readObject method is responsible for reading from the stream and
* restoring the classes fields. It may call in.defaultReadObject to invoke
* the default mechanism for restoring the object's non-static and
* non-transient fields. The defaultReadObject method uses information in
* the stream to assign the fields of the object saved in the stream with the
* correspondingly named fields in the current object. This handles the case
* when the class has evolved to add new fields. The method does not need to
* concern itself with the state belonging to its superclasses or subclasses.
* State is restored by reading data from the ObjectInputStream for
* the individual fields and making assignments to the appropriate fields
* of the object. Reading primitive data types is supported by DataInput.
! *
! * <p>The readObjectNoData method is responsible for initializing the state of
* the object for its particular class in the event that the serialization
* stream does not list the given class as a superclass of the object being
* deserialized. This may occur in cases where the receiving party uses a
* different version of the deserialized instance's class than the sending
* party, and the receiver's version extends classes that are not extended by
* the sender's version. This may also occur if the serialization stream has
* been tampered; hence, readObjectNoData is useful for initializing
* deserialized objects properly despite a "hostile" or incomplete source
* stream.
! *
! * <p>Serializable classes that need to designate an alternative object to be
* used when writing an object to the stream should implement this
* special method with the exact signature:
*
* <PRE>
* ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException;
! * </PRE><p>
*
* This writeReplace method is invoked by serialization if the method
* exists and it would be accessible from a method defined within the
* class of the object being serialized. Thus, the method can have private,
* protected and package-private access. Subclass access to this method
! * follows java accessibility rules. <p>
! *
* Classes that need to designate a replacement when an instance of it
* is read from the stream should implement this special method with the
* exact signature.
*
* <PRE>
* ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException;
! * </PRE><p>
*
* This readResolve method follows the same invocation rules and
! * accessibility rules as writeReplace.<p>
! *
* Enum types are all serializable and receive treatment defined by
* the <a href="{@docRoot}/../specs/serialization/index.html"><cite>
* Java Object Serialization Specification</cite></a> during
* serialization and deserialization. Any declarations of the special
! * handling methods discussed above are ignored for enum types.<p>
! *
* Record classes can implement {@code Serializable} and receive treatment defined
* by the <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records">
* <cite>Java Object Serialization Specification,</cite> Section 1.13,
* "Serialization of Records"</a>. Any declarations of the special
! * handling methods discussed above are ignored for record types.<p>
*
* The serialization runtime associates with each serializable class a version
* number, called a serialVersionUID, which is used during deserialization to
* verify that the sender and receiver of a serialized object have loaded
* classes for that object that are compatible with respect to serialization.
* throws IOException, ClassNotFoundException;
* private void readObjectNoData()
* throws ObjectStreamException;
* </PRE>
*
! * The writeObject method is responsible for writing the state of the
* object for its particular class so that the corresponding
* readObject method can restore it. The default mechanism for saving
* the Object's fields can be invoked by calling
* out.defaultWriteObject. The method does not need to concern
* itself with the state belonging to its superclasses or subclasses.
* State is saved by writing the individual fields to the
* ObjectOutputStream using the writeObject method or by using the
* methods for primitive data types supported by DataOutput.
! * <p>
! * The readObject method is responsible for reading from the stream and
* restoring the classes fields. It may call in.defaultReadObject to invoke
* the default mechanism for restoring the object's non-static and
* non-transient fields. The defaultReadObject method uses information in
* the stream to assign the fields of the object saved in the stream with the
* correspondingly named fields in the current object. This handles the case
* when the class has evolved to add new fields. The method does not need to
* concern itself with the state belonging to its superclasses or subclasses.
* State is restored by reading data from the ObjectInputStream for
* the individual fields and making assignments to the appropriate fields
* of the object. Reading primitive data types is supported by DataInput.
! * <p>
! * The readObjectNoData method is responsible for initializing the state of
* the object for its particular class in the event that the serialization
* stream does not list the given class as a superclass of the object being
* deserialized. This may occur in cases where the receiving party uses a
* different version of the deserialized instance's class than the sending
* party, and the receiver's version extends classes that are not extended by
* the sender's version. This may also occur if the serialization stream has
* been tampered; hence, readObjectNoData is useful for initializing
* deserialized objects properly despite a "hostile" or incomplete source
* stream.
! * <p>
! * Serializable classes that need to designate an alternative object to be
* used when writing an object to the stream should implement this
* special method with the exact signature:
*
* <PRE>
* ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException;
! * </PRE>
*
* This writeReplace method is invoked by serialization if the method
* exists and it would be accessible from a method defined within the
* class of the object being serialized. Thus, the method can have private,
* protected and package-private access. Subclass access to this method
! * follows java accessibility rules.
! * <p>
* Classes that need to designate a replacement when an instance of it
* is read from the stream should implement this special method with the
* exact signature.
*
* <PRE>
* ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException;
! * </PRE>
*
* This readResolve method follows the same invocation rules and
! * accessibility rules as writeReplace.
! * <p>
* Enum types are all serializable and receive treatment defined by
* the <a href="{@docRoot}/../specs/serialization/index.html"><cite>
* Java Object Serialization Specification</cite></a> during
* serialization and deserialization. Any declarations of the special
! * handling methods discussed above are ignored for enum types.
! * <p>
* Record classes can implement {@code Serializable} and receive treatment defined
* by the <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records">
* <cite>Java Object Serialization Specification,</cite> Section 1.13,
* "Serialization of Records"</a>. Any declarations of the special
! * handling methods discussed above, except {@code writeReplace},
+ * are ignored for record types.
+ *
+ * <div class="preview-block">
+ * <div class="preview-comment">
+ * <p>{@linkplain Class#isValue Value classes} that are not records can
+ * implement {@code Serializable}, but cannot be serialized directly. Instead,
+ * the {@code writeReplace} method should be used to designate an alternative
+ * object for serialization. At deserialization time, the alternative object
+ * can implement {@code readResolve} to construct the expected value class
+ * instance.
+ * </div>
+ * </div>
*
* The serialization runtime associates with each serializable class a version
* number, called a serialVersionUID, which is used during deserialization to
* verify that the sender and receiver of a serialized object have loaded
* classes for that object that are compatible with respect to serialization.
< prev index next >