/*

 * Copyright 1996-2004 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.io;

import java.io.ObjectOutput;

import java.io.ObjectInput;

/**

 * Only the identity of the class of an Externalizable instance is

 * written in the serialization stream and it is the responsibility

 * of the class to save and restore the contents of its instances.

 *

 * The writeExternal and readExternal methods of the Externalizable

 * interface are implemented by a class to give the class complete

 * control over the format and contents of the stream for an object

 * and its supertypes. These methods must explicitly

 * coordinate with the supertype to save its state. These methods supersede

 * customized implementations of writeObject and readObject methods.<br>

 *

 * Object Serialization uses the Serializable and Externalizable

 * interfaces.  Object persistence mechanisms can use them as well.  Each

 * object to be stored is tested for the Externalizable interface. If

 * the object supports Externalizable, the writeExternal method is called. If the

 * object does not support Externalizable and does implement

 * Serializable, the object is saved using

 * ObjectOutputStream. <br> When an Externalizable object is

 * reconstructed, an instance is created using the public no-arg

 * constructor, then the readExternal method called.  Serializable

 * objects are restored by reading them from an ObjectInputStream.<br>

 *

 * An Externalizable instance can designate a substitution object via

 * the writeReplace and readResolve methods documented in the Serializable

 * interface.<br>

 *

 * @author  unascribed

 * @see java.io.ObjectOutputStream

 * @see java.io.ObjectInputStream

 * @see java.io.ObjectOutput

 * @see java.io.ObjectInput

 * @see java.io.Serializable

 * @since   JDK1.1

 */

public interface Externalizable extends java.io.Serializable {

    /**

     * The object implements the writeExternal method to save its contents

     * by calling the methods of DataOutput for its primitive values or

     * calling the writeObject method of ObjectOutput for objects, strings,

     * and arrays.

     *

     * @serialData Overriding methods should use this tag to describe

     *             the data layout of this Externalizable object.

     *             List the sequence of element types and, if possible,

     *             relate the element to a public/protected field and/or

     *             method of this Externalizable class.

     *

     * @param out the stream to write the object to

     * @exception IOException Includes any I/O exceptions that may occur

     */

    void writeExternal(ObjectOutput out) throws IOException;

    /**

     * The object implements the readExternal method to restore its

     * contents by calling the methods of DataInput for primitive

     * types and readObject for objects, strings and arrays.  The

     * readExternal method must read the values in the same sequence

     * and with the same types as were written by writeExternal.

     *

     * @param in the stream to read data from in order to restore the object

     * @exception IOException if I/O errors occur

     * @exception ClassNotFoundException If the class for an object being

     *              restored cannot be found.

     */

    void readExternal(ObjectInput in) throws IOException, ClassNotFoundException;

}