 |
Chapter 11 The java.io Package |
 |
|
Chapter 11 The java.io Package |
|
java.io.ObjectInputStream
java.io.InputStream
None
java.io.ObjectInput
New as of JDK 1.1
The ObjectInputStream class can read both primitive types and object instances from an underlying InputStream. The objects and other data must have been written by an ObjectOutputStream. These two classes can provide persistent storage of objects when they are used in conjunction with FileInputStream and FileOutputStream. The classes can also be used with socket streams to pass objects across the network.
Only objects that are instances of classes that implement the Serializable or Externalizable interfaces can be deserialized from an input stream. The default deserialization mechanism is implemented by readObject(). When an object is deserialized, the non-static and non-transient fields of the object are restored to the values they had when the object was serialized, including any other objects referenced by the object (except for those objects that do not implement the Serializable interface themselves). Graphs of objects are restored using a reference sharing mechanism. New object instances are always allocated during the deserialization process, to prevent existing objects from being overwritten. Deserialized objects are returned as instances of type Object, so they should be cast to the appropriate type. Strings and arrays are objects in Java, so they are treated as objects during deserialization.
For example, the following code opens a file called color.ser and reads a Color object:
FileInputStream fileIn;
ObjectInputStream in;
Color color;
try {
fileIn = new FileInputStream("color.ser");
in = new ObjectInputStream(fileIn);
color = (Color)in.readObject();
in.close();
}
catch (Exception e) {
System.out.println("Error reading: " + e);
}
Classes that have transient instance variables may require special handling to reconstruct the values of these variables when objects are deserialized. Special handling may also be necessary to correctly deserialize objects that were serialized with a different version of their class than is in use when they are deserialized. Classes that require special handling during serialization and deserialization must implement the following methods (with these exact signatures):
private void readObject(ObjectOutputStream stream)
throws IOException, ClassNotFoundException
private void writeObject(ObjectOutputStream stream) throws IOException
The writeObject() method is responsible for writing the state of the object for the particular class so that it can be restored by readObject(). The readObject() method registers an object validation callback by calling registerValidation() as its first action. The readObject() method doesn't need to handle reading the state for the object's superclass or any of its subclasses except in the case where the superclass doesn't itself implement the Serializable interface. In this case, the nonserializable class must have a no-argument constructor that can be called to initialize its fields, and it is the responsibility of the subclass to restore the state of its superclass.
A class that inherits the implementation of Serializable prevents itself from being serialized by defining readObject() and writeObject() methods that throw NotSerializableException objects.
If a class needs complete control over the contents and formatting of the serialized form of its objects, it should implement the Externalizable interface.
public class java.io.ObjectInputStream extends java.io.InputStream
implements java.io.ObjectInput {
// Constructors
public ObjectInputStream(InputStream in);
// Public Instance Methods
public int available();
public void close();
public final void defaultReadObject();
public int read();
public int read(byte[] data, int offset, int length);
public boolean readBoolean();
public byte readByte();
public char readChar();
public double readDouble();
public float readFloat();
public void readFully(byte[] data);
public void readFully(byte[] data, int offset, int size);
public int readInt();
public String readLine();
public long readLong();
public final Object readObject();
public short readShort();
public int readUnsignedByte();
public int readUnsignedShort();
public String readUTF();
public synchronized void
registerValidation(ObjectInputValidation obj, int prio);
public int skipBytes(int len);
// Protected Instance Methods
protected final boolean enableResolveObject(boolean enable);
protected void readStreamHeader();
protected Class resolveClass(ObjectStreamClass v);
protected Object resolveObject(Object obj);
}
public ObjectInputStream(InputStream in) throws IOException, StreamCorruptedException
The underlying input stream.
If any kind of I/O error occurs.
If the stream header is not correct.
This constructor creates an ObjectInputStream that reads from the given input stream. The constructor attempts to read the stream header, which consists of a magic number and a version number, and if something goes wrong, an appropriate exception is thrown. If all of the bytes of the stream header are not available, the constructor does not return until they become available.
The number of bytes that can be read without blocking.
If any kind of I/O error occurs.
ObjectInput.available()
InputStream.available()
This method returns the number of bytes that can be read without having to wait for more data to become available.
If any kind of I/O error occurs.
ObjectInput.close()
InputStream.close()
This method closes the stream and releases any system resources that are associated with it.
public final void defaultReadObject() throws IOException, ClassNotFoundException, NotActiveException
If any kind of I/O error occurs.
If the class of the object being read cannot be found.
If serialization is not active.
This method reads the fields of the current object that are not static and not transient. The method can only be called from the private readObject() method of an object that is being deserialized; it throws a NotActiveException if it is called at any other time. This method implements the default deserialization mechanism.
The next byte of data or -1 if the end of the stream is encountered.
If any kind of I/O error occurs.
ObjectInput.read()
InputStream.read()
This method reads the next byte from the stream. The method blocks until some data is available, the end of the stream is detected, or an exception is thrown.
public int read(byte[] data, int offset, int length) throws IOException
Array of bytes to be filled from the stream.
An offset into the byte array.
The number of bytes to read.
The number of bytes read or -1 if the end of the stream is encountered immediately.
If any kind of I/O error occurs.
ObjectInput.read(byte[], int, int)
InputStream.read(byte[], int, int)
This method reads up to length bytes of input into the given array starting at index offset. The method blocks until there is some input available.
The boolean value read from the stream.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readBoolean()
This method reads a byte as a boolean value from the underlying input stream. A byte that contains a zero is read as false. A byte that contains any other value is read as true. The method blocks until the byte is read, the end of the stream is encountered, or an exception is thrown.
The byte value read from the stream.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readByte()
This method reads a signed 8-bit value, a byte, from the underlying input stream. The method blocks until the byte is read, the end of the stream is encountered, or an exception is thrown.
The char value read from the stream.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readChar()
This method reads a 16-bit Unicode character from the stream. The method reads two bytes from the underlying input stream and then creates a char value using the first byte read as the most significant byte. The method blocks until the two bytes are read, the end of the stream is encountered, or an exception is thrown.
The double value read from the stream.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readDouble()
This method reads a 64-bit double quantity from the stream. The method reads a long value from the underlying input stream as if using the readLong() method. The long value is then converted to a double using the longBitsToDouble() method in Double. The method blocks until the necessary eight bytes are read, the end of the stream is encountered, or an exception is thrown.
The float value read from the stream.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readFloat()
This method reads a 32-bit float quantity from the stream. The method reads an int value from the underlying input stream as if using the readInt() method. The int value is then converted to a float using the intBitsToFloat() method in Float. The method blocks until the necessary four bytes are read, the end of the stream is encountered, or an exception is thrown.
The array to fill.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readFully(byte[])
This method reads bytes into the given array b until the array is full. The method reads repeatedly from the underlying stream to fill the array. The method blocks until all of the bytes are read, the end of the stream is encountered, or an exception is thrown.
public void readFully(byte[] data, int offset, int size) throws IOException
The array to fill.
An offset into the array.
The number of bytes to read.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readFully(byte[], int, int)
This method reads len bytes into the given array, starting at offset off. The method reads repeatedly from the underlying stream to fill the array. The method blocks until all of the bytes are read, the end of the stream is encountered, or an exception is thrown.
The int value read from the stream.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readInt()
This method reads a signed 32-bit int quantity from the stream. The method reads four bytes from the underlying input stream and then creates an int quantity, using the first byte read as the most significant byte. The method blocks until the four bytes are read, the end of the stream is encountered, or an exception is thrown.
A String that contains the line read from the stream.
If the end of the file is encountered.
If any other I/O error occurs.
DataInput.readLine()
This method reads the next line of text from the stream. The method reads bytes of data from the underlying input stream until it encounters a line terminator. A line terminator is a carriage return ("\r"), a newline character ("\n"), a carriage return immediately followed by a newline character, or the end of the stream. The method blocks until a line terminator is read, the end of the stream is encountered, or an exception is thrown. Note that this method calls the readLine() method of DataInputStream, which is deprecated in 1.1.
The long value read from the stream.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readLong()
This method reads a signed 64-bit long quantity from the stream. The method reads eight bytes from the underlying input stream and then creates a long quantity, using the first byte read as the most significant byte. The method blocks until the eight bytes are read, the end of the stream is encountered, or an exception is thrown.
public final Object readObject() throws OptionalDataException, ClassNotFoundException, IOException
An Object that has been deserialized from the stream.
If the object being deserialized has an unrecognized class.
If there is a problem with the class of the deserialized object.
If the stream serialization information is not correct.
If the stream contains primitive data instead of an object.
If any kind of I/O error occurs.
ObjectInput.readObject()
This method deserializes an object from the stream and returns a reference to the object. The non-static and non-transient fields of the object are restored to the values they had when the object was serialized. If the object contains references to other objects, these objects are also deserialized (as long as they implement the Serializable interface). Graphs of objects are restored using a reference-sharing mechanism. New object instances are always allocated during the deserialization process, to prevent existing objects from being overwritten. Deserialized objects are returned as instances of type Object, so they should be cast to the appropriate type.
Once an object has been completely restored (i.e., all of its fields and any objects it references have been restored), any object validation callbacks for the object or any of the objects it references are called in an order based on their priority. An object validation callback is registered by the private readObject() method for an object.
The short value read from the stream.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readShort()
This method reads a signed 16-bit short quantity from the stream. The method reads two bytes from the underlying input stream and then creates a short quantity, using the first byte read as the most significant byte. The method blocks until the two bytes are read, the end of the stream is encountered, or an exception is thrown.
The unsigned byte value read from the stream.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readUnsignedByte()
This method reads an unsigned 8-bit quantity from the stream. The method reads a byte from the underlying input stream and returns that byte. The method blocks until the byte is read, the end of the stream is encountered, or an exception is thrown.
The unsigned short value read from the stream.
If the end of the file is encountered.
If any other kind of I/O error occurs.
DataInput.readUnsignedShort()
This method reads an unsigned 16-bit quantity from the stream. The method reads two bytes from the underlying input stream and creates an unsigned short quantity using the first byte read as the most significant byte. The method blocks until the two bytes are read, the end of the stream is encountered, or an exception is thrown.
The String read from the stream.
If the end of the file is encountered.
If any other kind of I/O error occurs.
If the bytes do not represent a valid UTF-8 encoding.
DataInput.readUTF()
This method reads a UTF-8 encoded string from the stream. See the description of DataInputStream.readUTF(DataInput) for more information.
public synchronized void registerValidation( ObjectInputValidation obj, int prio) throws NotActiveException, InvalidObjectException
The object requesting validation.
The priority of the validation callback; use zero as a default.
If serialization is not active.
If obj is null.
This method may be called from an object's private readObject() method to register a validation callback. An object performs internal validation by implementing the ObjectInputValidation interface and registering itself with the ObjectInputStream via this function. When ObjectInputStream has completely deserialized an object (i.e., restored all of its fields and any objects it references), the stream calls ObjectInputValidation.validateObject() for every object that has an object validation callback. Objects that register with higher priority values get validated before objects that register with lower priority values. Within a priority value, the callbacks are not processed in any particular order.
The number of bytes to skip.
The actual number of skipped bytes.
If the end of the file is encountered.
If any other kind I/O error occurs.
DataInput.skipBytes()
This method skips over n bytes in the underlying input stream. The method blocks until all of the bytes are skipped, the end of the stream is encountered, or an exception is thrown.
protected final boolean enableResolveObject(boolean enable) throws SecurityException
A boolean value that specifies whether or not object replacement is enabled.
true if object replacement was previously enabled; false otherwise.
If enable is true and getClassLoader() called on the class of the stream does not return null.
This method determines if a trusted subclass of ObjectInputStream is allowed to replace deserialized objects. If the method is called with true, object replacement is enabled. Each time an object is deserialized, resolveObject() is called to give the ObjectInputStream a chance to replace the object. A trusted stream is one whose class has no ClassLoader.
protected void readStreamHeader() throws IOException, StreamCorruptedException
If the stream header is not correct.
If any kind of I/O error occurs.
This method attempts to read the stream header, which consists of a magic number and a version number. If something goes wrong, an appropriate exception is thrown. This method is called by the constructor for ObjectInputStream and is the source of the exceptions it throws. If you subclass ObjectInputStream, you can override this method to provide your own stream header checking.
protected Class resolveClass(ObjectStreamClass v) throws IOException, ClassNotFoundException
The ObjectStreamClass to be resolved.
The Class that corresponds to the given ObjectStreamClass.
If the class of the given ObjectStreamClass cannot be found.
If any kind of I/O error occurs.
This method attempts to find the Class object that corresponds to the supplied ObjectStreamClass. When a object is deserialized, its class information is read into an ObjectStreamClass object, which is then resolved to a Class if possible. Subclasses of ObjectInputStream can override this method to allow classes to be fetched from alternate sources. The version of the ObjectStreamClass and the Class must match.
The object to be replaced.
A replacement for the given object.
If any kind of I/O error occurs.
If object replacement is enabled for this ObjectInputStream (see enableResolveObject()), this method is called with each deserialized object to give the stream a chance to replace the object. In ObjectInputStream, this method simply returns the object that was passed to it. Subclasses can override this method to provide more useful functionality.
| Method | Inherited From | Method | Inherited From |
|---|---|---|---|
|
clone() |
Object |
equals(Object) |
Object |
|
finalize() |
Object |
getClass() |
Object |
|
hashCode() |
Object |
mark() |
InputStream |
|
markSupported() |
InputStream |
notify() |
Object |
|
notifyAll() |
Object |
read(byte[]) |
InputStream |
|
reset() |
InputStream |
skip(long n) |
InputStream |
|
toString() |
Object |
wait() |
Object |
|
wait(long) |
Object |
wait(long, int) |
Object |
Class, ClassNotFoundException, DataInput, Double, EOFException, Externalizable, Float, InputStream, InvalidClassException, IOException, NotActiveException, ObjectInput, ObjectInputValidation, ObjectOuputStream, ObjectStreamClass, OptionalDataException, SecurityException, Serializable, StreamCorruptedException, String, UTFDataFormatException
|
 |
|
| ObjectInput |  |
ObjectInputValidation |
