Showing the changes to java/pkg/java/io/Serializable.java (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,170 @@ | |||
| 1 | /* | ||
| 2 | * Copyright (c) 1996, 2005, 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: <p> | ||
| 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: <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 | * @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 JDK1.1 | ||
| 168 | */ | ||
| 169 | public interface Serializable { | ||
| 170 | } | ||