39 |
package java.io; |
package java.io; |
40 |
|
|
41 |
/** |
/** |
42 |
* This interface provides a way that classes can completely control how |
* This interface provides a way that classes can completely control how |
43 |
* the data of their object instances are written and read to and from |
* the data of their object instances are written and read to and from |
44 |
* streams. It has two methods which are used to write the data to a stream |
* streams. It has two methods which are used to write the data to a stream |
45 |
* and to read the data from a stream. The read method must read the data |
* and to read the data from a stream. The read method must read the data |
46 |
* in exactly the way it was written by the write method. |
* in exactly the way it was written by the write method. |
47 |
* <p> |
* <p> |
48 |
* Note that classes which implement this interface must take into account |
* Note that classes which implement this interface must take into account |
49 |
* that all superclass data must also be written to the stream as well. |
* that all superclass data must also be written to the stream as well. |
50 |
* The class implementing this interface must figure out how to make that |
* The class implementing this interface must figure out how to make that |
51 |
* happen. |
* happen. |
52 |
* <p> |
* <p> |
53 |
* This interface can be used to provide object persistence. When an |
* This interface can be used to provide object persistence. When an |
54 |
* object is to be stored externally, the <code>writeExternal</code> method is |
* object is to be stored externally, the <code>writeExternal</code> method is |
55 |
* called to save state. When the object is restored, an instance is |
* called to save state. When the object is restored, an instance is |
56 |
* created using the default no-argument constructor and the |
* created using the default no-argument constructor and the |
57 |
* <code>readExternal</code> method is used to restore the state. |
* <code>readExternal</code> method is used to restore the state. |
58 |
* |
* |
59 |
* @author Aaron M. Renn (arenn@urbanophile.com) |
* @author Aaron M. Renn (arenn@urbanophile.com) |
60 |
*/ |
*/ |
61 |
public interface Externalizable extends Serializable |
public interface Externalizable extends Serializable |
62 |
{ |
{ |
63 |
static final long serialVersionUID = -282491828744381764L; |
static final long serialVersionUID = -282491828744381764L; |
64 |
|
|
65 |
/** |
/** |
66 |
* This method restores an object's state by reading in the instance data |
* This method restores an object's state by reading in the instance data |
67 |
* for the object from the passed in stream. Note that this stream is not |
* for the object from the passed in stream. Note that this stream is not |
68 |
* a subclass of <code>InputStream</code>, but rather is a class that |
* a subclass of <code>InputStream</code>, but rather is a class that |
69 |
* implements |
* implements |
70 |
* the <code>ObjectInput</code> interface. That interface provides a |
* the <code>ObjectInput</code> interface. That interface provides a |
71 |
* mechanism for |
* mechanism for |
72 |
* reading in Java data types from a stream. |
* reading in Java data types from a stream. |
73 |
* <p> |
* <p> |
74 |
* Note that this method must be compatible with <code>writeExternal</code>. |
* Note that this method must be compatible with <code>writeExternal</code>. |
75 |
* It must read back the exact same types that were written by that |
* It must read back the exact same types that were written by that |
76 |
* method in the exact order they were written. |
* method in the exact order they were written. |
77 |
* <p> |
* <p> |
78 |
* If this method needs to read back an object instance, then the class |
* If this method needs to read back an object instance, then the class |
79 |
* for that object must be found and loaded. If that operation fails, |
* for that object must be found and loaded. If that operation fails, |
80 |
* then this method throws a <code>ClassNotFoundException</code> |
* then this method throws a <code>ClassNotFoundException</code> |
81 |
* |
* |
82 |
* @param in An <code>ObjectInput</code> instance for reading in the object |
* @param in An <code>ObjectInput</code> instance for reading in the object |
83 |
* state |
* state |
84 |
* |
* |
85 |
* @exception ClassNotFoundException If the class of an object being |
* @exception ClassNotFoundException If the class of an object being |
86 |
* restored cannot be found |
* restored cannot be found |
87 |
* @exception IOException If any other error occurs |
* @exception IOException If any other error occurs |
88 |
*/ |
*/ |
89 |
public abstract void readExternal(ObjectInput in) |
public abstract void readExternal(ObjectInput in) |
90 |
throws ClassNotFoundException, IOException; |
throws ClassNotFoundException, IOException; |
91 |
|
|
|
/*************************************************************************/ |
|
|
|
|
92 |
/** |
/** |
93 |
* This method is responsible for writing the instance data of an object |
* This method is responsible for writing the instance data of an object |
94 |
* to the passed in stream. Note that this stream is not a subclass of |
* to the passed in stream. Note that this stream is not a subclass of |
95 |
* <code>OutputStream</code>, but rather is a class that implements the |
* <code>OutputStream</code>, but rather is a class that implements the |
96 |
* <code>ObjectOutput</code> interface. That interface provides a |
* <code>ObjectOutput</code> interface. That interface provides a |
97 |
* number of methods |
* number of methods |
98 |
* for writing Java data values to a stream. |
* for writing Java data values to a stream. |
99 |
* <p> |
* <p> |
100 |
* Not that the implementation of this method must be coordinated with |
* Not that the implementation of this method must be coordinated with |
101 |
* the implementation of <code>readExternal</code>. |
* the implementation of <code>readExternal</code>. |
102 |
* |
* |
103 |
* @param out An <code>ObjectOutput</code> instance for writing the |
* @param out An <code>ObjectOutput</code> instance for writing the |
104 |
* object state |
* object state |
105 |
* |
* |
106 |
* @exception IOException If an error occurs |
* @exception IOException If an error occurs |
107 |
*/ |
*/ |
108 |
public abstract void writeExternal(ObjectOutput out) throws IOException; |
public abstract void writeExternal(ObjectOutput out) throws IOException; |
109 |
|
|
110 |
} // interface Externalizable |
} // interface Externalizable |