1. /*

  2.  * @(#)Externalizable.java	1.17 03/01/23

  3.  *

  4.  * Copyright 2003 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.io;

  9. 

  10. import java.io.ObjectOutput;

  11. import java.io.ObjectInput;

  12. 

  13. /**

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

  15.  * written in the serialization stream and it is the responsibility

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

  17.  *

  18.  * The writeExternal and readExternal methods of the Externalizable

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

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

  21.  * and its supertypes. These methods must explicitly

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

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

  24.  *

  25.  * Object Serialization uses the Serializable and Externalizable

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

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

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

  29.  * object does not support Externalizable and does implement

  30.  * Serializable, the object is saved using

  31.  * ObjectOutputStream. <br> When an Externalizable object is

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

  33.  * constructor, then the readExternal method called.  Serializable

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

  35.  *

  36.  * An Externalizable instance can designate a substitution object via

  37.  * the writeReplace and readResolve methods documented in the Serializable

  38.  * interface.<br>

  39.  *

  40.  * @author  unascribed

  41.  * @version 1.17, 01/23/03

  42.  * @see java.io.ObjectOutputStream

  43.  * @see java.io.ObjectInputStream

  44.  * @see java.io.ObjectOutput

  45.  * @see java.io.ObjectInput

  46.  * @see java.io.Serializable

  47.  * @since   JDK1.1

  48.  */

  49. public interface Externalizable extends java.io.Serializable {

  50.     /**

  51.      * The object implements the writeExternal method to save its contents

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

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

  54.      * and arrays.

  55.      *

  56.      * @serialData Overriding methods should use this tag to describe

  57.      *             the data layout of this Externalizable object.

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

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

  60.      *             method of this Externalizable class.

  61.      *

  62.      * @param out the stream to write the object to

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

  64.      */

  65.     void writeExternal(ObjectOutput out) throws IOException;

  66. 

  67.     /**

  68.      * The object implements the readExternal method to restore its

  69.      * contents by calling the methods of DataInput for primitive

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

  71.      * readExternal method must read the values in the same sequence

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

  73.      *

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

  75.      * @exception IOException if I/O errors occur

  76.      * @exception ClassNotFoundException If the class for an object being

  77.      *              restored cannot be found.

  78.      */

  79.     void readExternal(ObjectInput in) throws IOException, ClassNotFoundException;

  80. }