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 }
|