1 /*
2 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
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. Classes that do not implement this
31 * interface will not have any of their state serialized or
32 * deserialized. All subtypes of a serializable class are themselves
33 * serializable. The serialization interface has no methods or fields
34 * and serves only to identify the semantics of being serializable. <p>
35 *
36 * To allow subtypes of non-serializable classes to be serialized, the
37 * subtype may assume responsibility for saving and restoring the
38 * state of the supertype's public, protected, and (if accessible)
39 * package fields. The subtype may assume this responsibility only if
40 * the class it extends has an accessible no-arg constructor to
41 * initialize the class's state. It is an error to declare a class
42 * Serializable if this is not the case. The error will be detected at
43 * runtime. <p>
44 *
45 * During deserialization, the fields of non-serializable classes will
46 * be initialized using the public or protected no-arg constructor of
47 * the class. A no-arg constructor must be accessible to the subclass
48 * that is serializable. The fields of serializable subclasses will
49 * be restored from the stream. <p>
50 *
51 * When traversing a graph, an object may be encountered that does not
52 * support the Serializable interface. In this case the
53 * NotSerializableException will be thrown and will identify the class
54 * of the non-serializable object. <p>
55 *
56 * Classes that require special handling during the serialization and
57 * deserialization process must implement special methods with these exact
58 * signatures:
59 *
60 * <PRE>
61 * private void writeObject(java.io.ObjectOutputStream out)
62 * throws IOException
63 * private void readObject(java.io.ObjectInputStream in)
64 * throws IOException, ClassNotFoundException;
65 * private void readObjectNoData()
66 * throws ObjectStreamException;
67 * </PRE>
68 *
69 * <p>The writeObject method is responsible for writing the state of the
70 * object for its particular class so that the corresponding
71 * readObject method can restore it. The default mechanism for saving
72 * the Object's fields can be invoked by calling
73 * out.defaultWriteObject. The method does not need to concern
74 * itself with the state belonging to its superclasses or subclasses.
75 * State is saved by writing the individual fields to the
76 * ObjectOutputStream using the writeObject method or by using the
77 * methods for primitive data types supported by DataOutput.
78 *
79 * <p>The readObject method is responsible for reading from the stream and
80 * restoring the classes fields. It may call in.defaultReadObject to invoke
81 * the default mechanism for restoring the object's non-static and
82 * non-transient fields. The defaultReadObject method uses information in
83 * the stream to assign the fields of the object saved in the stream with the
84 * correspondingly named fields in the current object. This handles the case
85 * when the class has evolved to add new fields. The method does not need to
86 * concern itself with the state belonging to its superclasses or subclasses.
87 * State is saved by writing the individual fields to the
88 * ObjectOutputStream using the writeObject method or by using the
89 * methods for primitive data types supported by DataOutput.
90 *
91 * <p>The readObjectNoData method is responsible for initializing the state of
92 * the object for its particular class in the event that the serialization
93 * stream does not list the given class as a superclass of the object being
94 * deserialized. This may occur in cases where the receiving party uses a
95 * different version of the deserialized instance's class than the sending
96 * party, and the receiver's version extends classes that are not extended by
97 * the sender's version. This may also occur if the serialization stream has
98 * been tampered; hence, readObjectNoData is useful for initializing
99 * 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:
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.
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>:
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 * @see java.io.ObjectOutputStream
163 * @see java.io.ObjectInputStream
164 * @see java.io.ObjectOutput
165 * @see java.io.ObjectInput
166 * @see java.io.Externalizable
167 * @since 1.1
168 */
169 public interface Serializable {
170 }