KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > io > Externalizable


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 JavaDoc;
11 import java.io.ObjectInput JavaDoc;
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 JavaDoc {
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 JavaDoc out) throws IOException JavaDoc;
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 JavaDoc in) throws IOException JavaDoc, ClassNotFoundException JavaDoc;
80 }
81
Popular Tags