001: /*
002: * Copyright 1996-2005 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.io;
027:
028: /**
029: * Serializability of a class is enabled by the class implementing the
030: * java.io.Serializable interface. Classes that do not implement this
031: * interface will not have any of their state serialized or
032: * deserialized. All subtypes of a serializable class are themselves
033: * serializable. The serialization interface has no methods or fields
034: * and serves only to identify the semantics of being serializable. <p>
035: *
036: * To allow subtypes of non-serializable classes to be serialized, the
037: * subtype may assume responsibility for saving and restoring the
038: * state of the supertype's public, protected, and (if accessible)
039: * package fields. The subtype may assume this responsibility only if
040: * the class it extends has an accessible no-arg constructor to
041: * initialize the class's state. It is an error to declare a class
042: * Serializable if this is not the case. The error will be detected at
043: * runtime. <p>
044: *
045: * During deserialization, the fields of non-serializable classes will
046: * be initialized using the public or protected no-arg constructor of
047: * the class. A no-arg constructor must be accessible to the subclass
048: * that is serializable. The fields of serializable subclasses will
049: * be restored from the stream. <p>
050: *
051: * When traversing a graph, an object may be encountered that does not
052: * support the Serializable interface. In this case the
053: * NotSerializableException will be thrown and will identify the class
054: * of the non-serializable object. <p>
055: *
056: * Classes that require special handling during the serialization and
057: * deserialization process must implement special methods with these exact
058: * signatures: <p>
059: *
060: * <PRE>
061: * private void writeObject(java.io.ObjectOutputStream out)
062: * throws IOException
063: * private void readObject(java.io.ObjectInputStream in)
064: * throws IOException, ClassNotFoundException;
065: * private void readObjectNoData()
066: * throws ObjectStreamException;
067: * </PRE>
068: *
069: * <p>The writeObject method is responsible for writing the state of the
070: * object for its particular class so that the corresponding
071: * readObject method can restore it. The default mechanism for saving
072: * the Object's fields can be invoked by calling
073: * out.defaultWriteObject. The method does not need to concern
074: * itself with the state belonging to its superclasses or subclasses.
075: * State is saved by writing the individual fields to the
076: * ObjectOutputStream using the writeObject method or by using the
077: * methods for primitive data types supported by DataOutput.
078: *
079: * <p>The readObject method is responsible for reading from the stream and
080: * restoring the classes fields. It may call in.defaultReadObject to invoke
081: * the default mechanism for restoring the object's non-static and
082: * non-transient fields. The defaultReadObject method uses information in
083: * the stream to assign the fields of the object saved in the stream with the
084: * correspondingly named fields in the current object. This handles the case
085: * when the class has evolved to add new fields. The method does not need to
086: * concern itself with the state belonging to its superclasses or subclasses.
087: * State is saved by writing the individual fields to the
088: * ObjectOutputStream using the writeObject method or by using the
089: * methods for primitive data types supported by DataOutput.
090: *
091: * <p>The readObjectNoData method is responsible for initializing the state of
092: * the object for its particular class in the event that the serialization
093: * stream does not list the given class as a superclass of the object being
094: * deserialized. This may occur in cases where the receiving party uses a
095: * different version of the deserialized instance's class than the sending
096: * party, and the receiver's version extends classes that are not extended by
097: * the sender's version. This may also occur if the serialization stream has
098: * been tampered; hence, readObjectNoData is useful for initializing
099: * deserialized objects properly despite a "hostile" or incomplete source
100: * stream.
101: *
102: * <p>Serializable classes that need to designate an alternative object to be
103: * used when writing an object to the stream should implement this
104: * special method with the exact signature: <p>
105: *
106: * <PRE>
107: * ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException;
108: * </PRE><p>
109: *
110: * This writeReplace method is invoked by serialization if the method
111: * exists and it would be accessible from a method defined within the
112: * class of the object being serialized. Thus, the method can have private,
113: * protected and package-private access. Subclass access to this method
114: * follows java accessibility rules. <p>
115: *
116: * Classes that need to designate a replacement when an instance of it
117: * is read from the stream should implement this special method with the
118: * exact signature.<p>
119: *
120: * <PRE>
121: * ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException;
122: * </PRE><p>
123: *
124: * This readResolve method follows the same invocation rules and
125: * accessibility rules as writeReplace.<p>
126: *
127: * The serialization runtime associates with each serializable class a version
128: * number, called a serialVersionUID, which is used during deserialization to
129: * verify that the sender and receiver of a serialized object have loaded
130: * classes for that object that are compatible with respect to serialization.
131: * If the receiver has loaded a class for the object that has a different
132: * serialVersionUID than that of the corresponding sender's class, then
133: * deserialization will result in an {@link InvalidClassException}. A
134: * serializable class can declare its own serialVersionUID explicitly by
135: * declaring a field named <code>"serialVersionUID"</code> that must be static,
136: * final, and of type <code>long</code>:<p>
137: *
138: * <PRE>
139: * ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L;
140: * </PRE>
141: *
142: * If a serializable class does not explicitly declare a serialVersionUID, then
143: * the serialization runtime will calculate a default serialVersionUID value
144: * for that class based on various aspects of the class, as described in the
145: * Java(TM) Object Serialization Specification. However, it is <em>strongly
146: * recommended</em> that all serializable classes explicitly declare
147: * serialVersionUID values, since the default serialVersionUID computation is
148: * highly sensitive to class details that may vary depending on compiler
149: * implementations, and can thus result in unexpected
150: * <code>InvalidClassException</code>s during deserialization. Therefore, to
151: * guarantee a consistent serialVersionUID value across different java compiler
152: * implementations, a serializable class must declare an explicit
153: * serialVersionUID value. It is also strongly advised that explicit
154: * serialVersionUID declarations use the <code>private</code> modifier where
155: * possible, since such declarations apply only to the immediately declaring
156: * class--serialVersionUID fields are not useful as inherited members. Array
157: * classes cannot declare an explicit serialVersionUID, so they always have
158: * the default computed value, but the requirement for matching
159: * serialVersionUID values is waived for array classes.
160: *
161: * @author unascribed
162: * @version 1.31, 05/05/07
163: * @see java.io.ObjectOutputStream
164: * @see java.io.ObjectInputStream
165: * @see java.io.ObjectOutput
166: * @see java.io.ObjectInput
167: * @see java.io.Externalizable
168: * @since JDK1.1
169: */
170: public interface Serializable {
171: }
| 