1 /* 2 * @(#)Externalizable.java 1.19 04/01/12 3 * 4 * Copyright 2004 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 supersede 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.19, 01/12/04 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 } 81