/*
* 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 {
}