jaroslav@56: * jaroslav@56: * To allow subtypes of non-serializable classes to be serialized, the jaroslav@56: * subtype may assume responsibility for saving and restoring the jaroslav@56: * state of the supertype's public, protected, and (if accessible) jaroslav@56: * package fields. The subtype may assume this responsibility only if jaroslav@56: * the class it extends has an accessible no-arg constructor to jaroslav@56: * initialize the class's state. It is an error to declare a class jaroslav@56: * Serializable if this is not the case. The error will be detected at jaroslav@56: * runtime.
jaroslav@56: * jaroslav@56: * During deserialization, the fields of non-serializable classes will jaroslav@56: * be initialized using the public or protected no-arg constructor of jaroslav@56: * the class. A no-arg constructor must be accessible to the subclass jaroslav@56: * that is serializable. The fields of serializable subclasses will jaroslav@56: * be restored from the stream.
jaroslav@56: * jaroslav@56: * When traversing a graph, an object may be encountered that does not jaroslav@56: * support the Serializable interface. In this case the jaroslav@56: * NotSerializableException will be thrown and will identify the class jaroslav@56: * of the non-serializable object.
jaroslav@56: * jaroslav@56: * Classes that require special handling during the serialization and jaroslav@56: * deserialization process must implement special methods with these exact jaroslav@56: * signatures:
jaroslav@56: * jaroslav@56: *
jaroslav@56: * private void writeObject(java.io.ObjectOutputStream out) jaroslav@56: * throws IOException jaroslav@56: * private void readObject(java.io.ObjectInputStream in) jaroslav@56: * throws IOException, ClassNotFoundException; jaroslav@56: * private void readObjectNoData() jaroslav@56: * throws ObjectStreamException; jaroslav@56: *jaroslav@56: * jaroslav@56: *
The writeObject method is responsible for writing the state of the jaroslav@56: * object for its particular class so that the corresponding jaroslav@56: * readObject method can restore it. The default mechanism for saving jaroslav@56: * the Object's fields can be invoked by calling jaroslav@56: * out.defaultWriteObject. The method does not need to concern jaroslav@56: * itself with the state belonging to its superclasses or subclasses. jaroslav@56: * State is saved by writing the individual fields to the jaroslav@56: * ObjectOutputStream using the writeObject method or by using the jaroslav@56: * methods for primitive data types supported by DataOutput. jaroslav@56: * jaroslav@56: *
The readObject method is responsible for reading from the stream and jaroslav@56: * restoring the classes fields. It may call in.defaultReadObject to invoke jaroslav@56: * the default mechanism for restoring the object's non-static and jaroslav@56: * non-transient fields. The defaultReadObject method uses information in jaroslav@56: * the stream to assign the fields of the object saved in the stream with the jaroslav@56: * correspondingly named fields in the current object. This handles the case jaroslav@56: * when the class has evolved to add new fields. The method does not need to jaroslav@56: * concern itself with the state belonging to its superclasses or subclasses. jaroslav@56: * State is saved by writing the individual fields to the jaroslav@56: * ObjectOutputStream using the writeObject method or by using the jaroslav@56: * methods for primitive data types supported by DataOutput. jaroslav@56: * jaroslav@56: *
The readObjectNoData method is responsible for initializing the state of jaroslav@56: * the object for its particular class in the event that the serialization jaroslav@56: * stream does not list the given class as a superclass of the object being jaroslav@56: * deserialized. This may occur in cases where the receiving party uses a jaroslav@56: * different version of the deserialized instance's class than the sending jaroslav@56: * party, and the receiver's version extends classes that are not extended by jaroslav@56: * the sender's version. This may also occur if the serialization stream has jaroslav@56: * been tampered; hence, readObjectNoData is useful for initializing jaroslav@56: * deserialized objects properly despite a "hostile" or incomplete source jaroslav@56: * stream. jaroslav@56: * jaroslav@56: *
Serializable classes that need to designate an alternative object to be jaroslav@56: * used when writing an object to the stream should implement this jaroslav@56: * special method with the exact signature:
jaroslav@56: * jaroslav@56: *
jaroslav@56: * ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException; jaroslav@56: *
jaroslav@56: * jaroslav@56: * This writeReplace method is invoked by serialization if the method jaroslav@56: * exists and it would be accessible from a method defined within the jaroslav@56: * class of the object being serialized. Thus, the method can have private, jaroslav@56: * protected and package-private access. Subclass access to this method jaroslav@56: * follows java accessibility rules.
jaroslav@56: * jaroslav@56: * Classes that need to designate a replacement when an instance of it jaroslav@56: * is read from the stream should implement this special method with the jaroslav@56: * exact signature.
jaroslav@56: * jaroslav@56: *
jaroslav@56: * ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException; jaroslav@56: *
jaroslav@56: * jaroslav@56: * This readResolve method follows the same invocation rules and jaroslav@56: * accessibility rules as writeReplace.
jaroslav@56: *
jaroslav@56: * The serialization runtime associates with each serializable class a version
jaroslav@56: * number, called a serialVersionUID, which is used during deserialization to
jaroslav@56: * verify that the sender and receiver of a serialized object have loaded
jaroslav@56: * classes for that object that are compatible with respect to serialization.
jaroslav@56: * If the receiver has loaded a class for the object that has a different
jaroslav@56: * serialVersionUID than that of the corresponding sender's class, then
jaroslav@56: * deserialization will result in an {@link InvalidClassException}. A
jaroslav@56: * serializable class can declare its own serialVersionUID explicitly by
jaroslav@56: * declaring a field named "serialVersionUID" that must be static,
jaroslav@56: * final, and of type long:
jaroslav@56: * jaroslav@56: *
jaroslav@56: * ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L; jaroslav@56: *jaroslav@56: * jaroslav@56: * If a serializable class does not explicitly declare a serialVersionUID, then jaroslav@56: * the serialization runtime will calculate a default serialVersionUID value jaroslav@56: * for that class based on various aspects of the class, as described in the jaroslav@56: * Java(TM) Object Serialization Specification. However, it is strongly jaroslav@56: * recommended that all serializable classes explicitly declare jaroslav@56: * serialVersionUID values, since the default serialVersionUID computation is jaroslav@56: * highly sensitive to class details that may vary depending on compiler jaroslav@56: * implementations, and can thus result in unexpected jaroslav@56: *
InvalidClassExceptions during deserialization. Therefore, to
jaroslav@56: * guarantee a consistent serialVersionUID value across different java compiler
jaroslav@56: * implementations, a serializable class must declare an explicit
jaroslav@56: * serialVersionUID value. It is also strongly advised that explicit
jaroslav@56: * serialVersionUID declarations use the private modifier where
jaroslav@56: * possible, since such declarations apply only to the immediately declaring
jaroslav@56: * class--serialVersionUID fields are not useful as inherited members. Array
jaroslav@56: * classes cannot declare an explicit serialVersionUID, so they always have
jaroslav@56: * the default computed value, but the requirement for matching
jaroslav@56: * serialVersionUID values is waived for array classes.
jaroslav@56: *
jaroslav@56: * @author unascribed
jaroslav@56: * @see java.io.ObjectOutputStream
jaroslav@56: * @see java.io.ObjectInputStream
jaroslav@56: * @see java.io.ObjectOutput
jaroslav@56: * @see java.io.ObjectInput
jaroslav@56: * @see java.io.Externalizable
jaroslav@56: * @since JDK1.1
jaroslav@56: */
jaroslav@56: public interface Serializable {
jaroslav@56: }