1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.io; 19 20 /** 21 * Marks classes that can be serialized by {@link ObjectOutputStream} and 22 * deserialized by {@link ObjectInputStream}. 23 * 24 * <p><strong>Warning:</strong> this interface limits how its implementing 25 * classes can change in the future. By implementing {@code Serializable} you 26 * expose your flexible in-memory implementation details as a rigid binary 27 * representation. Simple code changes--like renaming private fields--are 28 * not safe when the changed class is serializable. 29 * 30 * <h3>The Serialized Form</h3> 31 * By default, the serialization mechanism encodes an object's class name, the 32 * names of its non-transient fields (including non-public fields), and the 33 * values of all of those fields. The output is an opaque sequence of bytes. 34 * Those bytes can be decoded into a new, equivalent instance as long as the 35 * decoder has compatible versions of the originating classes. 36 * 37 * <p>Changing the class name, field names or field types breaks serialization 38 * compatibility and complicates interoperability between old and new versions 39 * of the serializable class. Adding or removing fields also complicates 40 * serialization between versions of a class because it requires your code to 41 * cope with missing fields. 42 * 43 * <p>Every serializable class is assigned a version identifier called a {@code 44 * serialVersionUID}. By default, this identifier is computed by hashing the 45 * class declaration and its members. This identifier is included in the 46 * serialized form so that version conflicts can be detected during 47 * deserialization. If the local {@code serialVersionUID} differs from the 48 * {@code serialVersionUID} in the serialized data, deserialization will fail 49 * with an {@link InvalidClassException}. 50 * 51 * <p>You can avoid this failure by declaring an explicit {@code 52 * serialVersionUID}. Declaring an explicit {@code serialVersionUID} tells the 53 * serialization mechanism that the class is forward and backward compatible 54 * with all versions that share that {@code serialVersionUID}. Declaring a 55 * {@code serialVersionUID} looks like this: <pre> {@code 56 * 57 * private static final long serialVersionUID = 0L; 58 * }</pre> 59 * If you declare a {@code serialVersionUID}, you should increment it each 60 * time your class changes incompatibly with the previous version. Typically 61 * this is when you add, change or remove a non-transient field. 62 * 63 * <p>You can take control of your serialized form by implementing these two 64 * methods with these exact signatures in your serializable classes: 65 * <pre> {@code 66 * 67 * private void writeObject(java.io.ObjectOutputStream out) 68 * throws IOException { 69 * // write 'this' to 'out'... 70 * } 71 * 72 * private void readObject(java.io.ObjectInputStream in) 73 * throws IOException, ClassNotFoundException { 74 * // populate the fields of 'this' from the data in 'in'... 75 * } 76 * }</pre> 77 * It is impossible to maintain serialization compatibility across a class name 78 * change. For this reason, implementing {@code Serializable} in anonymous 79 * inner classes is highly discouraged: simply reordering the members in the 80 * file could change the generated class name and break serialization 81 * compatibility. 82 * 83 * <p>You can exclude member fields from serialization by giving them the {@code 84 * transient} modifier. Upon deserialization, the transient field's value will 85 * be null, 0, or false according to its type. 86 * 87 * <h3>Implement Serializable Judiciously</h3> 88 * Refer to <i>Effective Java</i>'s chapter on serialization for thorough 89 * coverage of the serialization API. The book explains how to use this 90 * interface without harming your application's maintainability. 91 * 92 * <h3>Recommended Alternatives</h3> 93 * <strong>JSON</strong> is concise, human-readable and efficient. Android 94 * includes both a {@link android.util.JsonReader streaming API} and a {@link 95 * org.json.JSONObject tree API} to read and write JSON. Use a binding library 96 * like <a href="http://code.google.com/p/google-gson/">GSON</a> to read and 97 * write Java objects directly. 98 */ 99 public interface Serializable { 100 } 101
