public class

ObjectInputStream

extends InputStream
implements ObjectInput ObjectStreamConstants
java.lang.Object
   ↳ java.io.InputStream
     ↳ java.io.ObjectInputStream

Class Overview

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.

Summary

Nested Classes
class ObjectInputStream.GetField GetField is an inner class that provides access to the persistent fields read from the source stream. 
[Expand]
Inherited Constants
From interface java.io.ObjectStreamConstants
Public Constructors
ObjectInputStream(InputStream input)
Constructs a new ObjectInputStream that reads from the InputStream input.
Protected Constructors
ObjectInputStream()
Constructs a new ObjectInputStream.
Public Methods
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.
int read(byte[] buffer, int offset, int length)
Reads at most length bytes from the source stream and stores them in byte array buffer starting at offset count.
int read()
Reads a single byte from the source stream and returns it as an integer in the range from 0 to 255.
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.
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[] buffer, int offset, int length)
Reads bytes from the source stream into the byte array buffer.
void readFully(byte[] buffer)
Reads bytes from the source stream into the byte array buffer.
int readInt()
Reads an integer (32 bit) from the source stream.
String readLine()
This method is deprecated. Use BufferedReader
long readLong()
Reads a long (64 bit) from the source stream.
final Object readObject()
Reads the next object from the source stream.
short readShort()
Reads a short (16 bit) from the source stream.
String readUTF()
Reads a string encoded in modified UTF-8 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.
synchronized void registerValidation(ObjectInputValidation object, int priority)
Registers a callback for post-deserialization validation of objects.
int skipBytes(int length)
Skips length bytes on the source stream.
Protected Methods
boolean enableResolveObject(boolean enable)
Enables object replacement for this stream.
ObjectStreamClass readClassDescriptor()
Reads a class descriptor from the source stream.
Object readObjectOverride()
Method to be overriden by subclasses to read the next object from the source stream.
void readStreamHeader()
Reads and validates the ObjectInputStream header from the source stream.
Class<?> resolveClass(ObjectStreamClass osClass)
Loads the Java class corresponding to the class descriptor osClass that has just been read from the source stream.
Object resolveObject(Object object)
Allows trusted subclasses to substitute the specified original object with a new object.
Class<?> resolveProxyClass(String[] interfaceNames)
Creates the proxy class that implements the interfaces specified in interfaceNames.
[Expand]
Inherited Methods
From class java.io.InputStream
From class java.lang.Object
From interface java.io.Closeable
From interface java.io.DataInput
From interface java.io.ObjectInput

Public Constructors

public ObjectInputStream (InputStream input)

Since: API Level 1

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.
SecurityException if a security manager is installed and it denies subclassing this class.

Protected Constructors

protected ObjectInputStream ()

Since: API Level 1

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.
SecurityException if a security manager is installed and it denies subclassing this class.

Public Methods

public int available ()

Since: API Level 1

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, 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.

Returns
  • the estimated number of bytes available
Throws
IOException

public void close ()

Since: API Level 1

Closes this stream. This implementation closes the source stream.

Throws
IOException if an error occurs while closing this stream.

public void defaultReadObject ()

Since: API Level 1

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().

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

Since: API Level 1

Reads at most length bytes from the source stream and stores them in byte array buffer starting at offset count. Blocks until count bytes have been read, the end of the source stream is detected or an exception is thrown.

Parameters
buffer the array in which to store the bytes read.
offset the initial position in buffer to store the bytes read from the source stream.
length the maximum number of bytes to store in buffer.
Returns
  • the number of bytes read or -1 if the end of the source input stream has been reached.
Throws
IndexOutOfBoundsException if offset < 0 or length < 0, or if offset + length is greater than the length of buffer.
IOException if an error occurs while reading from this stream.
NullPointerException if buffer is null.

public int read ()

Since: API Level 1

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.

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.

public boolean readBoolean ()

Since: API Level 1

Reads a boolean from the source stream.

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.

public byte readByte ()

Since: API Level 1

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

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.

public char readChar ()

Since: API Level 1

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

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.

public double readDouble ()

Since: API Level 1

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

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.

public ObjectInputStream.GetField readFields ()

Since: API Level 1

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.

public float readFloat ()

Since: API Level 1

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

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.

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

Since: API Level 1

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

Parameters
buffer the byte array in which to store the bytes read.
offset the initial position in buffer to store the bytes read from the source stream.
length the maximum number of bytes to store in buffer.
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.

public void readFully (byte[] buffer)

Since: API Level 1

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

Parameters
buffer 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.

public int readInt ()

Since: API Level 1

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

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.

public String readLine ()

Since: API Level 1

This method is deprecated.
Use BufferedReader

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

Returns
  • the string read from the source stream.
Throws
IOException if an error occurs while reading from the source stream.

public long readLong ()

Since: API Level 1

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

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.

public final Object readObject ()

Since: API Level 1

Reads 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.

public short readShort ()

Since: API Level 1

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

Returns
  • the short value read from the source stream.
Throws
IOException if an error occurs while reading from the source stream.

public String readUTF ()

Since: API Level 1

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

Returns
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.

public Object readUnshared ()

Since: API Level 1

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.

public int readUnsignedByte ()

Since: API Level 1

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

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.

public int readUnsignedShort ()

Since: API Level 1

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

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.

public synchronized void registerValidation (ObjectInputValidation object, int priority)

Since: API Level 1

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

public int skipBytes (int length)

Since: API Level 1

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).

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.

Protected Methods

protected boolean enableResolveObject (boolean enable)

Since: API Level 1

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.
Throws
SecurityException if a security manager is installed and it denies enabling object replacement for this stream.

protected ObjectStreamClass readClassDescriptor ()

Since: API Level 1

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.

protected Object readObjectOverride ()

Since: API Level 1

Method to be overriden 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.

protected void readStreamHeader ()

Since: API Level 1

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.

protected Class<?> resolveClass (ObjectStreamClass osClass)

Since: API Level 1

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.

protected Object resolveObject (Object object)

Since: API Level 1

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.

protected Class<?> resolveProxyClass (String[] interfaceNames)

Since: API Level 1

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.