java.io

Class ObjectInputStream

java.lang.Object

java.io.InputStream

java.io.ObjectInputStream

All Implemented Interfaces:

Closeable, DataInput, ObjectInput, ObjectStreamConstants, AutoCloseable

public class ObjectInputStream
extends InputStream
implements ObjectInput, ObjectStreamConstants

A specialized InputStream that is able to read (deserialize) Java objects as well as primitive data types (int, byte, char etc.). The data has typically been saved using an ObjectOutputStream.

See Also:

ObjectOutputStream, ObjectInput, Serializable, Externalizable

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ObjectInputStream.GetField GetField is an inner class that provides access to the persistent fields read from the source stream.

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

Constructors

Modifier	Constructor and Description
protected	ObjectInputStream() Constructs a new ObjectInputStream.
	ObjectInputStream(InputStream input) Constructs a new ObjectInputStream that reads from the InputStream input.

Method Summary

Modifier and Type	Method and Description
int	available() Returns an estimated number of bytes that can be read or skipped without blocking for more input.
void	close() Closes this stream.
void	defaultReadObject() Default method to read objects from this stream.
protected boolean	enableResolveObject(boolean enable) Enables object replacement for this stream.
int	read() Reads a single byte from the source stream and returns it as an integer in the range from 0 to 255.
int	read(byte[] buffer, int byteOffset, int byteCount) Reads up to byteCount bytes from this stream and stores them in the byte array buffer starting at byteOffset.
boolean	readBoolean() Reads a boolean from the source stream.
byte	readByte() Reads a byte (8 bit) from the source stream.
char	readChar() Reads a character (16 bit) from the source stream.
protected ObjectStreamClass	readClassDescriptor() Reads a class descriptor from the source stream.
double	readDouble() Reads a double (64 bit) from the source stream.
ObjectInputStream.GetField	readFields() Reads the persistent fields of the object that is currently being read from the source stream.
float	readFloat() Reads a float (32 bit) from the source stream.
void	readFully(byte[] dst) Reads bytes from the source stream into the byte array dst.
void	readFully(byte[] dst, int offset, int byteCount) Reads byteCount bytes from the source stream into the byte array dst.
int	readInt() Reads an integer (32 bit) from the source stream.
String	readLine() Deprecated. Use BufferedReader instead.
long	readLong() Reads a long (64 bit) from the source stream.
Object	readObject() Reads the next object from the source stream.
protected Object	readObjectOverride() Method to be overridden by subclasses to read the next object from the source stream.
short	readShort() Reads a short (16 bit) from the source stream.
protected void	readStreamHeader() Reads and validates the ObjectInputStream header from the source stream.
Object	readUnshared() Reads the next unshared object from the source stream.
int	readUnsignedByte() Reads an unsigned byte (8 bit) from the source stream.
int	readUnsignedShort() Reads an unsigned short (16 bit) from the source stream.
String	readUTF() Reads a string encoded in modified UTF-8 from the source stream.
void	registerValidation(ObjectInputValidation object, int priority) Registers a callback for post-deserialization validation of objects.
protected Class<?>	resolveClass(ObjectStreamClass osClass) Loads the Java class corresponding to the class descriptor osClass that has just been read from the source stream.
protected Object	resolveObject(Object object) Allows trusted subclasses to substitute the specified original object with a new object.
protected Class<?>	resolveProxyClass(String[] interfaceNames) Creates the proxy class that implements the interfaces specified in interfaceNames.
int	skipBytes(int length) Skips length bytes on the source stream.

Methods inherited from class java.io.InputStream

mark, markSupported, nullInputStream, read, readAllBytes, readNBytes, readNBytes, reset, skip, transferTo

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

Constructs a new ObjectInputStream. This default constructor can be used by subclasses that do not want to use the public constructor if it allocates unneeded data.

Throws:

IOException - if an error occurs when creating this stream.

ObjectInputStream

public ObjectInputStream(InputStream input)
                  throws StreamCorruptedException,
                         IOException

Constructs a new ObjectInputStream that reads from the InputStream input.

Parameters:

input - the non-null source InputStream to filter reads on.

Throws:

IOException - if an error occurs while reading the stream header.

StreamCorruptedException - if the source stream does not contain serialized objects that can be read.

Method Detail

available

public int available()
              throws IOException

Description copied from class: InputStream

Returns an estimated number of bytes that can be read or skipped without blocking for more input.

Note that this method provides such a weak guarantee that it is not very useful in practice.

Firstly, the guarantee is "without blocking for more input" rather than "without blocking": a read may still block waiting for I/O to complete — the guarantee is merely that it won't have to wait indefinitely for data to be written. The result of this method should not be used as a license to do I/O on a thread that shouldn't be blocked.

Secondly, the result is a conservative estimate and may be significantly smaller than the actual number of bytes available. In particular, an implementation that always returns 0 would be correct. In general, callers should only use this method if they'd be satisfied with treating the result as a boolean yes or no answer to the question "is there definitely data ready?".

Thirdly, the fact that a given number of bytes is "available" does not guarantee that a read or skip will actually read or skip that many bytes: they may read or skip fewer.

It is particularly important to realize that you must not use this method to size a container and assume that you can read the entirety of the stream without needing to resize the container. Such callers should probably write everything they read to a ByteArrayOutputStream and convert that to a byte array. Alternatively, if you're reading from a file, File.length() returns the current length of the file (though assuming the file's length can't change may be incorrect, reading a file is inherently racy).

The default implementation of this method in InputStream always returns 0. Subclasses should override this method if they are able to indicate the number of bytes available.

Specified by:

available in interface ObjectInput

Overrides:

available in class InputStream

Returns:

the estimated number of bytes available

Throws:

IOException - if this stream is closed or an error occurs

close

public void close()
           throws IOException

Closes this stream. This implementation closes the source stream.

Specified by:

close in interface Closeable

Specified by:

close in interface ObjectInput

Specified by:

close in interface AutoCloseable

Overrides:

close in class InputStream

Throws:

IOException - if an error occurs while closing this stream.

defaultReadObject

public void defaultReadObject()
                       throws IOException,
                              ClassNotFoundException,
                              NotActiveException

Default method to read objects from this stream. Serializable fields defined in the object's class and superclasses are read from the source stream.

Throws:

ClassNotFoundException - if the object's class cannot be found.

IOException - if an I/O error occurs while reading the object data.

NotActiveException - if this method is not called from readObject().

See Also:

ObjectOutputStream.defaultWriteObject()

enableResolveObject

protected boolean enableResolveObject(boolean enable)

Enables object replacement for this stream. By default this is not enabled. Only trusted subclasses (loaded with system class loader) are allowed to change this status.

Parameters:

enable - true to enable object replacement; false to disable it.

Returns:

the previous setting.

See Also:

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

read

public int read()
         throws IOException

Reads a single byte from the source stream and returns it as an integer in the range from 0 to 255. Returns -1 if the end of the source stream has been reached. Blocks if no input is available.

Specified by:

read in interface ObjectInput

Specified by:

read in class InputStream

Returns:

the byte read or -1 if the end of the source stream has been reached.

Throws:

IOException - if an error occurs while reading from this stream.

read

public int read(byte[] buffer,
                int byteOffset,
                int byteCount)
         throws IOException

Description copied from class: InputStream

Reads up to byteCount bytes from this stream and stores them in the byte array buffer starting at byteOffset. Returns the number of bytes actually read or -1 if the end of the stream has been reached.

Specified by:

read in interface ObjectInput

Overrides:

read in class InputStream

Throws:

IOException - if the stream is closed or another IOException occurs.

readBoolean

public boolean readBoolean()
                    throws IOException

Reads a boolean from the source stream.

Specified by:

readBoolean in interface DataInput

Returns:

the boolean value read from the source stream.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

See Also:

DataOutput.writeBoolean(boolean)

readByte

public byte readByte()
              throws IOException

Reads a byte (8 bit) from the source stream.

Specified by:

readByte in interface DataInput

Returns:

the byte value read from the source stream.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

See Also:

DataOutput.writeByte(int)

readChar

public char readChar()
              throws IOException

Reads a character (16 bit) from the source stream.

Specified by:

readChar in interface DataInput

Returns:

the char value read from the source stream.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

See Also:

DataOutput.writeChar(int)

readDouble

public double readDouble()
                  throws IOException

Reads a double (64 bit) from the source stream.

Specified by:

readDouble in interface DataInput

Returns:

the double value read from the source stream.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

See Also:

DataOutput.writeDouble(double)

readFields

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

Reads the persistent fields of the object that is currently being read from the source stream. The values read are stored in a GetField object that provides access to the persistent fields. This GetField object is then returned.

Returns:

the GetField object from which persistent fields can be accessed by name.

Throws:

ClassNotFoundException - if the class of an object being deserialized can not be found.

IOException - if an error occurs while reading from this stream.

NotActiveException - if this stream is currently not reading an object.

readFloat

public float readFloat()
                throws IOException

Reads a float (32 bit) from the source stream.

Specified by:

readFloat in interface DataInput

Returns:

the float value read from the source stream.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

See Also:

DataOutput.writeFloat(float)

readFully

public void readFully(byte[] dst)
               throws IOException

Reads bytes from the source stream into the byte array dst. This method will block until dst.length bytes have been read.

Specified by:

readFully in interface DataInput

Parameters:

dst - the array in which to store the bytes read.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

readFully

public void readFully(byte[] dst,
                      int offset,
                      int byteCount)
               throws IOException

Reads byteCount bytes from the source stream into the byte array dst.

Specified by:

readFully in interface DataInput

Parameters:

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

offset - the initial position in dst to store the bytes read from the source stream.

byteCount - the number of bytes to read.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

readInt

public int readInt()
            throws IOException

Reads an integer (32 bit) from the source stream.

Specified by:

readInt in interface DataInput

Returns:

the integer value read from the source stream.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

See Also:

DataOutput.writeInt(int)

readLine

@Deprecated
public String readLine()
                            throws IOException

Deprecated. Use BufferedReader instead.

Reads the next line from the source stream. Lines are terminated by '\r', '\n', "\r\n" or an EOF.

Specified by:

readLine in interface DataInput

Returns:

the string read from the source stream.

Throws:

IOException - if an error occurs while reading from the source stream.

readLong

public long readLong()
              throws IOException

Reads a long (64 bit) from the source stream.

Specified by:

readLong in interface DataInput

Returns:

the long value read from the source stream.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

See Also:

DataOutput.writeLong(long)

readClassDescriptor

protected ObjectStreamClass readClassDescriptor()
                                         throws IOException,
                                                ClassNotFoundException

Reads a class descriptor from the source stream.

Returns:

the class descriptor read from the source stream.

Throws:

ClassNotFoundException - if a class for one of the objects cannot be found.

IOException - if an error occurs while reading from the source stream.

resolveProxyClass

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

Creates the proxy class that implements the interfaces specified in interfaceNames.

Parameters:

interfaceNames - the interfaces used to create the proxy class.

Returns:

the proxy class.

Throws:

ClassNotFoundException - if the proxy class or any of the specified interfaces cannot be created.

IOException - if an error occurs while reading from the source stream.

See Also:

ObjectOutputStream.annotateProxyClass(Class)

readObject

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

Reads the next object from the source stream.

Specified by:

readObject in interface ObjectInput

Returns:

the object read from the source stream.

Throws:

ClassNotFoundException - if the class of one of the objects in the object graph cannot be found.

IOException - if an error occurs while reading from the source stream.

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

See Also:

ObjectOutputStream.writeObject(Object)

readUnshared

public Object readUnshared()
                    throws IOException,
                           ClassNotFoundException

Reads the next unshared object from the source stream.

Returns:

the new object read.

Throws:

ClassNotFoundException - if the class of one of the objects in the object graph cannot be found.

IOException - if an error occurs while reading from the source stream.

See Also:

ObjectOutputStream.writeUnshared(java.lang.Object)

readObjectOverride

protected Object readObjectOverride()
                             throws OptionalDataException,
                                    ClassNotFoundException,
                                    IOException

Method to be overridden by subclasses to read the next object from the source stream.

Returns:

the object read from the source stream.

Throws:

ClassNotFoundException - if the class of one of the objects in the object graph cannot be found.

IOException - if an error occurs while reading from the source stream.

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 a short (16 bit) from the source stream.

Specified by:

readShort in interface DataInput

Returns:

the short value read from the source stream.

Throws:

IOException - if an error occurs while reading from the source stream.

See Also:

DataOutput.writeShort(int)

readStreamHeader

protected void readStreamHeader()
                         throws IOException,
                                StreamCorruptedException

Reads and validates the ObjectInputStream header from the source stream.

Throws:

IOException - if an error occurs while reading from the source stream.

StreamCorruptedException - if the source stream does not contain readable serialized objects.

readUnsignedByte

public int readUnsignedByte()
                     throws IOException

Reads an unsigned byte (8 bit) from the source stream.

Specified by:

readUnsignedByte in interface DataInput

Returns:

the unsigned byte value read from the source stream packaged in an integer.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

See Also:

DataOutput.writeByte(int)

readUnsignedShort

public int readUnsignedShort()
                      throws IOException

Reads an unsigned short (16 bit) from the source stream.

Specified by:

readUnsignedShort in interface DataInput

Returns:

the unsigned short value read from the source stream packaged in an integer.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

See Also:

DataOutput.writeShort(int)

readUTF

public String readUTF()
               throws IOException

Reads a string encoded in modified UTF-8 from the source stream.

Specified by:

readUTF in interface DataInput

Returns:

the string encoded in modified UTF-8 read from the source stream.

Throws:

EOFException - if the end of the input is reached before the read request can be satisfied.

IOException - if an error occurs while reading from the source stream.

See Also:

DataOutput.writeUTF(java.lang.String)

registerValidation

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

Registers a callback for post-deserialization validation of objects. It allows to perform additional consistency checks before the readObject() method of this class returns its result to the caller. This method can only be called from within the readObject() method of a class that implements "special" deserialization rules. It can be called multiple times. Validation callbacks are then done in order of decreasing priority, defined by priority.

Parameters:

object - an object that can validate itself by receiving a callback.

priority - the validator's priority.

Throws:

InvalidObjectException - if object is null.

NotActiveException - if this stream is currently not reading objects. In that case, calling this method is not allowed.

See Also:

ObjectInputValidation.validateObject()

resolveClass

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

Loads the Java class corresponding to the class descriptor osClass that has just been read from the source stream.

Parameters:

osClass - an ObjectStreamClass read from the source stream.

Returns:

a Class corresponding to the descriptor osClass.

Throws:

ClassNotFoundException - if the class for an object cannot be found.

IOException - if an I/O error occurs while creating the class.

See Also:

ObjectOutputStream.annotateClass(Class)

resolveObject

protected Object resolveObject(Object object)
                        throws IOException

Allows trusted subclasses to substitute the specified original object with a new object. Object substitution has to be activated first with calling enableResolveObject(true). This implementation just returns object.

Parameters:

object - the original object for which a replacement may be defined.

Returns:

the replacement object for object.

Throws:

IOException - if any I/O error occurs while creating the replacement object.

See Also:

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

skipBytes

public int skipBytes(int length)
              throws IOException

Skips length bytes on the source stream. This method should not be used to skip bytes at any arbitrary position, just when reading primitive data types (int, char etc).

Specified by:

skipBytes in interface DataInput

Parameters:

length - the number of bytes to skip.

Returns:

the number of bytes actually skipped.

Throws:

IOException - if an error occurs while skipping bytes on the source stream.

NullPointerException - if the source stream is null.