xref: /libcore/luni/src/main/java/java/io/Serializable.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package java.io;

/**
 * Marks classes that can be serialized by {@link ObjectOutputStream} and
 * deserialized by {@link ObjectInputStream}.
 *
 * <p><strong>Warning:</strong> this interface limits how its implementing
 * classes can change in the future. By implementing {@code Serializable} you
 * expose your flexible in-memory implementation details as a rigid binary
 * representation. Simple code changes--like renaming private fields--are
 * not safe when the changed class is serializable.
 *
 * <h3>The Serialized Form</h3>
 * By default, the serialization mechanism encodes an object's class name, the
 * names of its non-transient fields (including non-public fields), and the
 * values of all of those fields. The output is an opaque sequence of bytes.
 * Those bytes can be decoded into a new, equivalent instance as long as the
 * decoder has compatible versions of the originating classes.
 *
 * <p>Changing the class name, field names or field types breaks serialization
 * compatibility and complicates interoperability between old and new versions
 * of the serializable class. Adding or removing fields also complicates
 * serialization between versions of a class because it requires your code to
 * cope with missing fields.
 *
 * <p>Every serializable class is assigned a version identifier called a {@code
 * serialVersionUID}. By default, this identifier is computed by hashing the
 * class declaration and its members. This identifier is included in the
 * serialized form so that version conflicts can be detected during
 * deserialization. If the local {@code serialVersionUID} differs from the
 * {@code serialVersionUID} in the serialized data, deserialization will fail
 * with an {@link InvalidClassException}.
 *
 * <p>You can avoid this failure by declaring an explicit {@code
 * serialVersionUID}. Declaring an explicit {@code serialVersionUID} tells the
 * serialization mechanism that the class is forward and backward compatible
 * with all versions that share that {@code serialVersionUID}. Declaring a
 * {@code serialVersionUID} looks like this: <pre>   {@code
 *
 *     private static final long serialVersionUID = 0L;
 * }</pre>
 * If you declare a {@code serialVersionUID}, you should increment it each
 * time your class changes incompatibly with the previous version. Typically
 * this is when you add, change or remove a non-transient field.
 *
 * <p>You can take control of your serialized form by implementing these two
 * methods with these exact signatures in your serializable classes:
 * <pre>   {@code
 *
 *   private void writeObject(java.io.ObjectOutputStream out)
 *       throws IOException {
 *     // write 'this' to 'out'...
 *   }
 *
 *   private void readObject(java.io.ObjectInputStream in)
 *       throws IOException, ClassNotFoundException {
 *     // populate the fields of 'this' from the data in 'in'...
 *   }
 * }</pre>
 * It is impossible to maintain serialization compatibility across a class name
 * change. For this reason, implementing {@code Serializable} in anonymous
 * inner classes is highly discouraged: simply reordering the members in the
 * file could change the generated class name and break serialization
 * compatibility.
 *
 * <p>You can exclude member fields from serialization by giving them the {@code
 * transient} modifier. Upon deserialization, the transient field's value will
 * be null, 0, or false according to its type.
 *
 * <h3>Implement Serializable Judiciously</h3>
 * Refer to <i>Effective Java</i>'s chapter on serialization for thorough
 * coverage of the serialization API. The book explains how to use this
 * interface without harming your application's maintainability.
 *
 * <h3>Recommended Alternatives</h3>
 * <strong>JSON</strong> is concise, human-readable and efficient. Android
 * includes both a {@link android.util.JsonReader streaming API} and a {@link
 * org.json.JSONObject tree API} to read and write JSON. Use a binding library
 * like <a href="http://code.google.com/p/google-gson/">GSON</a> to read and
 * write Java objects directly.
 */
public interface Serializable {
}