java.io
Class ObjectInputStream

java.lang.Object
  java.io.InputStream
      java.io.ObjectInputStream

All Implemented Interfaces:

Closeable, DataInput, ObjectInput, ObjectStreamConstants

public class ObjectInputStream
extends InputStream
implements ObjectInput, ObjectStreamConstants

An ObjectInputStream can be used to load Java objects from a stream where the objects were saved using an ObjectOutputStream. Primitive data (ints, bytes, chars, etc) can also be loaded if the data was saved as primitive types as well. It is invalid to attempt to read an object as primitive data.

See Also:

ObjectOutputStream, ObjectInput, Serializable, Externalizable

Nested Class Summary

static class	ObjectInputStream.GetField Inner class to provide access to serializable fields
(package private) static class	ObjectInputStream.InputValidationDesc

Field Summary

Fields inherited from interface java.io.ObjectStreamConstants

baseWireHandle, PROTOCOL_VERSION_1, PROTOCOL_VERSION_2, SC_BLOCK_DATA, SC_ENUM, SC_EXTERNALIZABLE, SC_SERIALIZABLE, SC_WRITE_METHOD, STREAM_MAGIC, STREAM_VERSION, SUBCLASS_IMPLEMENTATION_PERMISSION, SUBSTITUTION_PERMISSION, TC_ARRAY, TC_BASE, TC_BLOCKDATA, TC_BLOCKDATALONG, TC_CLASS, TC_CLASSDESC, TC_ENDBLOCKDATA, TC_ENUM, TC_EXCEPTION, TC_LONGSTRING, TC_MAX, TC_NULL, TC_OBJECT, TC_PROXYCLASSDESC, TC_REFERENCE, TC_RESET, TC_STRING

Constructor Summary

protected	ObjectInputStream() Constructs a new ObjectInputStream.
	ObjectInputStream(InputStream input) Constructs a new ObjectInputStream on the InputStream input.

Method Summary

int	available() Returns the number of bytes of primitive data available from the receiver.
void	close() Close this ObjectInputStream.
void	defaultReadObject() Default method to read objects from the receiver.
protected boolean	enableResolveObject(boolean enable) Enables/disables object replacement for the receiver.
int	read() Reads a single byte from the receiver and returns the result as an int.
int	read(byte[] buffer, int offset, int length) Reads at most length bytes from the receiver and stores them in byte array buffer starting at offset offset.
boolean	readBoolean() Reads and returns primitive data of type boolean read from the receiver
byte	readByte() Reads and returns primitive data of type byte read from the receiver
char	readChar() Reads and returns primitive data of type char read from the receiver
protected ObjectStreamClass	readClassDescriptor() Reads a new class descriptor from the receiver.
double	readDouble() Reads and returns primitive data of type double read from the receiver
ObjectInputStream.GetField	readFields() Reads the fields of the object being read from the stream.
float	readFloat() Reads and returns primitive data of type float read from the receiver
void	readFully(byte[] buffer) Reads bytes from the receiver into the byte array buffer.
void	readFully(byte[] buffer, int offset, int length) Reads bytes from the receiver into the byte array buffer.
int	readInt() Reads and returns primitive data of type int read from the receiver
String	readLine() Deprecated. Use BufferedReader
long	readLong() Reads and returns primitive data of type long read from the receiver
Object	readObject() Read the next object from the receiver's underlying stream.
protected Object	readObjectOverride() Method to be overriden by subclasses to read the next object from the receiver's underlying stream.
short	readShort() Reads and returns primitive data of type short from the receiver
protected void	readStreamHeader() Reads and validates the ObjectInputStream header from the receiver
Object	readUnshared() Read the next unshared object from the receiver's underlying stream.
int	readUnsignedByte() Reads and returns primitive data of type byte (unsigned) from the receiver
int	readUnsignedShort() Reads and returns primitive data of type short (unsigned) from the receiver
String	readUTF() Reads and returns primitive data of type String read in UTF format from the receiver
void	registerValidation(ObjectInputValidation object, int priority) Register object validator object to be executed to perform validation of objects loaded from the receiver.
protected Class<?>	resolveClass(ObjectStreamClass osClass) Loads the Java class corresponding to the class descriptor osClass(ObjectStreamClass) just read from the receiver.
protected Object	resolveObject(Object object) If enableResolveObject() was activated, computes the replacement object for the original object object and returns the replacement.
protected Class<?>	resolveProxyClass(String[] interfaceNames) Retrieves the proxy class corresponding to the interface names.
int	skipBytes(int length) Skips length bytes of primitive data from the receiver.

Methods inherited from class java.io.InputStream

mark, markSupported, read, reset, skip

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.io.ObjectInput

read, skip

Constructor Detail

ObjectInputStream

protected ObjectInputStream()
                     throws IOException,
                            SecurityException

Constructs a new ObjectInputStream. The representation and proper initialization is on the hands of subclasses.

Throws:

IOException - If not called from a subclass

SecurityException - If subclasses are not allowed

See Also:

SecurityManager.checkPermission(java.security.Permission)

ObjectInputStream

public ObjectInputStream(InputStream input)
                  throws StreamCorruptedException,
                         IOException

Constructs a new ObjectInputStream on the InputStream input. All reads are now filtered through this stream.

Parameters:

input - The non-null InputStream to filter reads on.

Throws:

IOException - If an IO exception happened when reading the stream header.

StreamCorruptedException - If the underlying stream does not contain serialized objects that can be read.

Method Detail

available

public int available()
              throws IOException

Returns the number of bytes of primitive data available from the receiver. It should not be used at any arbitrary position; just when reading primitive data types (ints, chars, etc).

Specified by:

available in interface ObjectInput

Overrides:

available in class InputStream

Returns:

the number of available primitive data bytes

Throws:

IOException - If any IO problem occurred when trying to compute the bytes available.

close

public void close()
           throws IOException

Close this ObjectInputStream. This implementation closes the target stream.

Specified by:

close in interface Closeable

Specified by:

close in interface ObjectInput

Overrides:

close in class InputStream

Throws:

IOException - If an error occurs attempting to close this stream.

defaultReadObject

public void defaultReadObject()
                       throws IOException,
                              ClassNotFoundException,
                              NotActiveException

Default method to read objects from the receiver. Fields defined in the object's class and super classes (which are Serializable) will be read.

Throws:

IOException - If an IO error occurs attempting to read the object data

ClassNotFoundException - If the class of the object cannot be found

NotActiveException - If this method is not called from readObject()

See Also:

ObjectOutputStream.defaultWriteObject()

enableResolveObject

protected boolean enableResolveObject(boolean enable)
                               throws SecurityException

Enables/disables object replacement for the receiver. By default this is not enabled. Only trusted subclasses (loaded with system class loader) can override this behavior.

Parameters:

enable - if true, enables replacement. If false, disables replacement.

Returns:

the previous configuration (if it was enabled or disabled)

Throws:

SecurityException - If the class of the receiver is not trusted

See Also:

resolveObject(java.lang.Object), ObjectOutputStream.enableReplaceObject(boolean)

read

public int read()
         throws IOException

Reads a single byte from the receiver and returns the result as an int. The low-order byte is returned or -1 of the end of stream was encountered.

Specified by:

read in interface ObjectInput

Specified by:

read in class InputStream

Returns:

The byte read or -1 if end of stream.

Throws:

IOException - If an IO exception happened when reading the primitive data.

read

public int read(byte[] buffer,
                int offset,
                int length)
         throws IOException

Reads at most length bytes from the receiver and stores them in byte array buffer starting at offset offset. Answer the number of bytes actually read or -1 if no bytes were read and end of stream was encountered.

Specified by:

read in interface ObjectInput

Overrides:

read in class InputStream

Parameters:

buffer - the byte array in which to store the read bytes.

offset - the offset in buffer to store the read bytes.

length - the maximum number of bytes to store in buffer.

Returns:

The number of bytes actually read or -1 if end of stream.

Throws:

IOException - If an IO exception happened when reading the primitive data.

readBoolean

public boolean readBoolean()
                    throws IOException

Reads and returns primitive data of type boolean read from the receiver

Specified by:

readBoolean in interface DataInput

Returns:

A boolean saved as primitive data using ObjectOutputStream.writeBoolean()

Throws:

IOException - If an IO exception happened when reading the primitive data.

See Also:

DataOutput.writeBoolean(boolean)

readByte

public byte readByte()
              throws IOException

Reads and returns primitive data of type byte read from the receiver

Specified by:

readByte in interface DataInput

Returns:

A byte saved as primitive data using ObjectOutputStream.writeByte()

Throws:

IOException - If an IO exception happened when reading the primitive data.

See Also:

DataOutput.writeByte(int)

readChar

public char readChar()
              throws IOException

Reads and returns primitive data of type char read from the receiver

Specified by:

readChar in interface DataInput

Returns:

A char saved as primitive data using ObjectOutputStream.writeChar()

Throws:

IOException - If an IO exception happened when reading the primitive data.

See Also:

DataOutput.writeChar(int)

readDouble

public double readDouble()
                  throws IOException

Reads and returns primitive data of type double read from the receiver

Specified by:

readDouble in interface DataInput

Returns:

A double saved as primitive data using ObjectOutputStream.writeDouble()

Throws:

IOException - If an IO exception happened when reading the primitive data.

See Also:

DataOutput.writeDouble(double)

readFields

public ObjectInputStream.GetField readFields()
                                      throws IOException,
                                             ClassNotFoundException,
                                             NotActiveException

Reads the fields of the object being read from the stream. The stream will use the currently active getField object, allowing users to load emulated fields, for cross-loading compatibility when a class definition changes.

Returns:

the fields being read

Throws:

IOException - If an IO exception happened

ClassNotFoundException - If a class of an object being de-serialized can not be found

NotActiveException - If there is no object currently being loaded (invalid to call this method)

readFloat

public float readFloat()
                throws IOException

Reads and returns primitive data of type float read from the receiver

Specified by:

readFloat in interface DataInput

Returns:

A float saved as primitive data using ObjectOutputStream.writeFloat()

Throws:

IOException - If an IO exception happened when reading the primitive data.

See Also:

DataOutput.writeFloat(float)

readFully

public void readFully(byte[] buffer)
               throws IOException

Reads bytes from the receiver into the byte array buffer. This method will block until buffer.length number of bytes have been read.

Specified by:

readFully in interface DataInput

Parameters:

buffer - the buffer to read bytes into

Throws:

IOException - if a problem occurs reading from this stream.

See Also:

DataOutput.write(byte[]), DataOutput.write(byte[], int, int)

readFully

public void readFully(byte[] buffer,
                      int offset,
                      int length)
               throws IOException

Reads bytes from the receiver into the byte array buffer. This method will block until length number of bytes have been read.

Specified by:

readFully in interface DataInput

Parameters:

buffer - the byte array in which to store the read bytes.

offset - the offset in buffer to store the read bytes.

length - the maximum number of bytes to store in buffer.

Throws:

IOException - if a problem occurs reading from this stream.

See Also:

DataOutput.write(byte[]), DataOutput.write(byte[], int, int)

readInt

public int readInt()
            throws IOException

Reads and returns primitive data of type int read from the receiver

Specified by:

readInt in interface DataInput

Returns:

an int saved as primitive data using ObjectOutputStream.writeInt()

Throws:

IOException - If an IO exception happened when reading the primitive data.

See Also:

DataOutput.writeInt(int)

readLine

@Deprecated
public String readLine()
                throws IOException

Deprecated. Use BufferedReader

Reads and returns the next line (primitive data of type String) read from the receiver

Specified by:

readLine in interface DataInput

Returns:

a String saved as primitive data using ObjectOutputStream.writeLine()

Throws:

IOException - If an IO exception happened when reading the primitive data.

readLong

public long readLong()
              throws IOException

Reads and returns primitive data of type long read from the receiver

Specified by:

readLong in interface DataInput

Returns:

a long saved as primitive data using ObjectOutputStream.writeLong()

Throws:

IOException - If an IO exception happened when reading the primitive data.

See Also:

DataOutput.writeLong(long)

readClassDescriptor

protected ObjectStreamClass readClassDescriptor()
                                         throws IOException,
                                                ClassNotFoundException

Reads a new class descriptor from the receiver. Return the class descriptor read.

Returns:

The ObjectStreamClass read from the stream.

Throws:

IOException - If an IO exception happened when reading the class descriptor.

ClassNotFoundException - If a class for one of the objects could not be found

resolveProxyClass

protected Class<?> resolveProxyClass(String[] interfaceNames)
                              throws IOException,
                                     ClassNotFoundException

Retrieves the proxy class corresponding to the interface names.

Parameters:

interfaceNames - The interfaces used to create the proxy class

Returns:

A proxy class

Throws:

IOException - If any IO problem occurred when trying to load the class.

ClassNotFoundException - If the proxy class cannot be created

readObject

public final Object readObject()
                        throws OptionalDataException,
                               ClassNotFoundException,
                               IOException

Read the next object from the receiver's underlying stream.

Specified by:

readObject in interface ObjectInput

Returns:

the new object read.

Throws:

IOException - If an IO exception happened when reading the object

ClassNotFoundException - If the class of one of the objects in the object graph could not be found

OptionalDataException - If primitive data types were found instead of an object.

See Also:

ObjectOutputStream.writeObject(Object)

readUnshared

public Object readUnshared()
                    throws IOException,
                           ClassNotFoundException

Read the next unshared object from the receiver's underlying stream.

Returns:

the new object read.

Throws:

IOException - If an IO exception happened when reading the object

ClassNotFoundException - If the class of one of the objects in the object graph could not be found

See Also:

ObjectOutputStream.writeUnshared(java.lang.Object)

readObjectOverride

protected Object readObjectOverride()
                             throws OptionalDataException,
                                    ClassNotFoundException,
                                    IOException

Method to be overriden by subclasses to read the next object from the receiver's underlying stream.

Returns:

the new object read.

Throws:

IOException - If an IO exception happened when reading the object

ClassNotFoundException - If the class of one of the objects in the object graph could not be found

OptionalDataException - If primitive data types were found instead of an object.

See Also:

ObjectOutputStream.writeObjectOverride(java.lang.Object)

readShort

public short readShort()
                throws IOException

Reads and returns primitive data of type short from the receiver

Specified by:

readShort in interface DataInput

Returns:

a short saved as primitive data using ObjectOutputStream.writeShort()

Throws:

IOException - If an IO exception happened when reading the primitive data.

See Also:

DataOutput.writeShort(int)

readStreamHeader

protected void readStreamHeader()
                         throws IOException,
                                StreamCorruptedException

Reads and validates the ObjectInputStream header from the receiver

Throws:

IOException - If an IO exception happened when reading the stream header.

StreamCorruptedException - If the underlying stream does not contain serialized objects that can be read.

readUnsignedByte

public int readUnsignedByte()
                     throws IOException

Reads and returns primitive data of type byte (unsigned) from the receiver

Specified by:

readUnsignedByte in interface DataInput

Returns:

a byte saved as primitive data using ObjectOutputStream.writeUnsignedByte()

Throws:

IOException - If an IO exception happened when reading the primitive data.

See Also:

DataOutput.writeByte(int)

readUnsignedShort

public int readUnsignedShort()
                      throws IOException

Reads and returns primitive data of type short (unsigned) from the receiver

Specified by:

readUnsignedShort in interface DataInput

Returns:

a short saved as primitive data using ObjectOutputStream.writeUnsignedShort()

Throws:

IOException - If an IO exception happened when reading the primitive data.

See Also:

DataOutput.writeShort(int)

readUTF

public String readUTF()
               throws IOException

Reads and returns primitive data of type String read in UTF format from the receiver

Specified by:

readUTF in interface DataInput

Returns:

a String saved as primitive data using ObjectOutputStream.writeUTF()

Throws:

IOException - If an IO exception happened when reading the primitive data.

See Also:

DataOutput.writeUTF(java.lang.String)

registerValidation

public void registerValidation(ObjectInputValidation object,
                               int priority)
                        throws NotActiveException,
                               InvalidObjectException

Register object validator object to be executed to perform validation of objects loaded from the receiver. Validations will be run in order of decreasing priority, defined by priority.

Parameters:

object - An ObjectInputValidation to validate objects loaded.

priority - validator priority

Throws:

NotActiveException - If this method is not called from readObject()

InvalidObjectException - If object is null.

resolveClass

protected Class<?> resolveClass(ObjectStreamClass osClass)
                         throws IOException,
                                ClassNotFoundException

Loads the Java class corresponding to the class descriptor osClass(ObjectStreamClass) just read from the receiver.

Parameters:

osClass - An ObjectStreamClass read from the receiver.

Returns:

a Class corresponding to the descriptor loaded.

Throws:

IOException - If any IO problem occurred when trying to load the class.

ClassNotFoundException - If the corresponding class cannot be found.

resolveObject

protected Object resolveObject(Object object)
                        throws IOException

If enableResolveObject() was activated, computes the replacement object for the original object object and returns the replacement. Otherwise returns object.

Parameters:

object - Original object for which a replacement may be defined

Returns:

a possibly new, replacement object for object

Throws:

IOException - If any IO problem occurred when trying to resolve the object.

See Also:

enableResolveObject(boolean), ObjectOutputStream.enableReplaceObject(boolean), ObjectOutputStream.replaceObject(java.lang.Object)

skipBytes

public int skipBytes(int length)
              throws IOException

Skips length bytes of primitive data from the receiver. It should not be used to skip bytes at any arbitrary position; just when reading primitive data types (ints, chars, etc).

Specified by:

skipBytes in interface DataInput

Parameters:

length - How many bytes to skip

Returns:

number of bytes skipped

Throws:

IOException - If any IO problem occurred when trying to skip the bytes.