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 // Android-added: Notes about serialVersionUID, using serialization judiciously, JSON. 29 // Android-removed: External links to serialization guidelinenes. 30 /** 31 * Serializability of a class is enabled by the class implementing the 32 * java.io.Serializable interface. 33 * 34 * <p><strong>Warning: Deserialization of untrusted data is inherently dangerous 35 * and should be avoided. Untrusted data should be carefully validated. 36 * </strong></p> 37 * 38 * Classes that do not implement this 39 * interface will not have any of their state serialized or 40 * deserialized. All subtypes of a serializable class are themselves 41 * serializable. The serialization interface has no methods or fields 42 * and serves only to identify the semantics of being serializable. <p> 43 * 44 * To allow subtypes of non-serializable classes to be serialized, the 45 * subtype may assume responsibility for saving and restoring the 46 * state of the supertype's public, protected, and (if accessible) 47 * package fields. The subtype may assume this responsibility only if 48 * the class it extends has an accessible no-arg constructor to 49 * initialize the class's state. It is an error to declare a class 50 * Serializable if this is not the case. The error will be detected at 51 * runtime. <p> 52 * 53 * During deserialization, the fields of non-serializable classes will 54 * be initialized using the public or protected no-arg constructor of 55 * the class. A no-arg constructor must be accessible to the subclass 56 * that is serializable. The fields of serializable subclasses will 57 * be restored from the stream. <p> 58 * 59 * When traversing a graph, an object may be encountered that does not 60 * support the Serializable interface. In this case the 61 * NotSerializableException will be thrown and will identify the class 62 * of the non-serializable object. <p> 63 * 64 * Classes that require special handling during the serialization and 65 * deserialization process must implement special methods with these exact 66 * signatures: 67 * 68 * <PRE> 69 * private void writeObject(java.io.ObjectOutputStream out) 70 * throws IOException 71 * private void readObject(java.io.ObjectInputStream in) 72 * throws IOException, ClassNotFoundException; 73 * private void readObjectNoData() 74 * throws ObjectStreamException; 75 * </PRE> 76 * 77 * <p>The writeObject method is responsible for writing the state of the 78 * object for its particular class so that the corresponding 79 * readObject method can restore it. The default mechanism for saving 80 * the Object's fields can be invoked by calling 81 * out.defaultWriteObject. The method does not need to concern 82 * itself with the state belonging to its superclasses or subclasses. 83 * State is saved by writing the individual fields to the 84 * ObjectOutputStream using the writeObject method or by using the 85 * methods for primitive data types supported by DataOutput. 86 * 87 * <p>The readObject method is responsible for reading from the stream and 88 * restoring the classes fields. It may call in.defaultReadObject to invoke 89 * the default mechanism for restoring the object's non-static and 90 * non-transient fields. The defaultReadObject method uses information in 91 * the stream to assign the fields of the object saved in the stream with the 92 * correspondingly named fields in the current object. This handles the case 93 * when the class has evolved to add new fields. The method does not need to 94 * concern itself with the state belonging to its superclasses or subclasses. 95 * State is restored by reading data from the ObjectInputStream for 96 * the individual fields and making assignments to the appropriate fields 97 * of the object. Reading primitive data types is supported by DataInput. 98 * 99 * <p>The readObjectNoData method is responsible for initializing the state of 100 * the object for its particular class in the event that the serialization 101 * stream does not list the given class as a superclass of the object being 102 * deserialized. This may occur in cases where the receiving party uses a 103 * different version of the deserialized instance's class than the sending 104 * party, and the receiver's version extends classes that are not extended by 105 * the sender's version. This may also occur if the serialization stream has 106 * been tampered; hence, readObjectNoData is useful for initializing 107 * deserialized objects properly despite a "hostile" or incomplete source 108 * stream. 109 * 110 * <p>Serializable classes that need to designate an alternative object to be 111 * used when writing an object to the stream should implement this 112 * special method with the exact signature: 113 * 114 * <PRE> 115 * ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException; 116 * </PRE><p> 117 * 118 * This writeReplace method is invoked by serialization if the method 119 * exists and it would be accessible from a method defined within the 120 * class of the object being serialized. Thus, the method can have private, 121 * protected and package-private access. Subclass access to this method 122 * follows java accessibility rules. <p> 123 * 124 * Classes that need to designate a replacement when an instance of it 125 * is read from the stream should implement this special method with the 126 * exact signature. 127 * 128 * <PRE> 129 * ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException; 130 * </PRE><p> 131 * 132 * This readResolve method follows the same invocation rules and 133 * accessibility rules as writeReplace.<p> 134 * 135 * The serialization runtime associates with each serializable class a version 136 * number, called a serialVersionUID, which is used during deserialization to 137 * verify that the sender and receiver of a serialized object have loaded 138 * classes for that object that are compatible with respect to serialization. 139 * If the receiver has loaded a class for the object that has a different 140 * serialVersionUID than that of the corresponding sender's class, then 141 * deserialization will result in an {@link InvalidClassException}. A 142 * serializable class can declare its own serialVersionUID explicitly by 143 * declaring a field named <code>"serialVersionUID"</code> that must be static, 144 * final, and of type <code>long</code>: 145 * 146 * <PRE> 147 * ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L; 148 * </PRE> 149 * 150 * If a serializable class does not explicitly declare a serialVersionUID, then 151 * the serialization runtime will calculate a default serialVersionUID value 152 * for that class based on various aspects of the class, as described in the 153 * Java(TM) Object Serialization Specification. However, it is <em>strongly 154 * recommended</em> that all serializable classes explicitly declare 155 * serialVersionUID values, since the default serialVersionUID computation is 156 * highly sensitive to class details that may vary depending on compiler 157 * implementations, and can thus result in unexpected 158 * <code>InvalidClassException</code>s during deserialization. Therefore, to 159 * guarantee a consistent serialVersionUID value across different java compiler 160 * implementations, a serializable class must declare an explicit 161 * serialVersionUID value. It is also strongly advised that explicit 162 * serialVersionUID declarations use the <code>private</code> modifier where 163 * possible, since such declarations apply only to the immediately declaring 164 * class--serialVersionUID fields are not useful as inherited members. Array 165 * classes cannot declare an explicit serialVersionUID, so they always have 166 * the default computed value, but the requirement for matching 167 * serialVersionUID values is waived for array classes. 168 * 169 * Android implementation of serialVersionUID computation will change slightly 170 * for some classes if you're targeting android N. In order to preserve compatibility, 171 * this change is only enabled if the application target SDK version is set to 172 * 24 or higher. It is highly recommended to use an explicit serialVersionUID 173 * field to avoid compatibility issues. 174 * 175 * <h3>Implement Serializable Judiciously</h3> 176 * Refer to <i>Effective Java</i>'s chapter on serialization for thorough 177 * coverage of the serialization API. The book explains how to use this 178 * interface without harming your application's maintainability. 179 * 180 * <h3>Recommended Alternatives</h3> 181 * <strong>JSON</strong> is concise, human-readable and efficient. Android 182 * includes both a {@link android.util.JsonReader streaming API} and a {@link 183 * org.json.JSONObject tree API} to read and write JSON. Use a binding library 184 * like <a href="http://code.google.com/p/google-gson/">GSON</a> to read and 185 * write Java objects directly. 186 * 187 * @author unascribed 188 * @see java.io.ObjectOutputStream 189 * @see java.io.ObjectInputStream 190 * @see java.io.ObjectOutput 191 * @see java.io.ObjectInput 192 * @see java.io.Externalizable 193 * @since 1.1 194 */ 195 public interface Serializable { 196 } 197