to top

fullscreen Use Tree Navigation

Since: API Level 1

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

int	PROTOCOL_VERSION_1	Stream protocol version 1.
int	PROTOCOL_VERSION_2	Stream protocol version 2.
byte	SC_BLOCK_DATA	Bit mask for the `flag` field in ObjectStreamClass.
byte	SC_ENUM	Bit mask for the `flag` field in ObjectStreamClass.
byte	SC_EXTERNALIZABLE	Bit mask for the `flag` field in ObjectStreamClass.
byte	SC_SERIALIZABLE	Bit mask for the `flag` field in ObjectStreamClass.
byte	SC_WRITE_METHOD	Bit mask for the `flag` field in ObjectStreamClass.
short	STREAM_MAGIC	The stream header's magic number.
short	STREAM_VERSION	The stream header's version number.
byte	TC_ARRAY	Tag to mark a new array.
byte	TC_BASE	The minimum tag value.
byte	TC_BLOCKDATA	Tag to mark a block of optional data.
byte	TC_BLOCKDATALONG	Tag to mark a long block of data.
byte	TC_CLASS	Tag to mark a reference to a class.
byte	TC_CLASSDESC	Tag to mark a new class descriptor.
byte	TC_ENDBLOCKDATA	Tag to mark the end of block data blocks for an object.
byte	TC_ENUM	Tag to mark a new enum.
byte	TC_EXCEPTION	Tag to mark an exception.
byte	TC_LONGSTRING	Tag to mark a long string.
byte	TC_MAX	The maximum tag value.
byte	TC_NULL	Tag to mark a `null` object reference.
byte	TC_OBJECT	Tag to mark a new object.
byte	TC_PROXYCLASSDESC	Tag to mark a new proxy class descriptor.
byte	TC_REFERENCE	Tag to mark a reference to an object that has already been written to the stream.
byte	TC_RESET	Tag to mark a stream reset.
byte	TC_STRING	Tag to mark a new string.
int	baseWireHandle	Handle for the first object that gets serialized.

[Expand]

Inherited Fields

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[] 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() 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 overridden 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

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	mark(int readlimit) Sets a mark position in this InputStream.
boolean	markSupported() Indicates whether this stream supports the `mark()` and `reset()` methods.
int	read(byte[] buffer) Equivalent to `read(buffer, 0, buffer.length)`.
abstract int	read() Reads a single byte from this stream and returns it as an integer in the range from 0 to 255.
int	read(byte[] buffer, int offset, int length) Reads at most `length` bytes from this stream and stores them in the byte array `b` starting at `offset`.
synchronized void	reset() Resets this stream to the last marked location.
long	skip(long byteCount) Skips at most `n` bytes in this stream.

From class java.lang.Object

Object	clone() Creates and returns a copy of this `Object`.
boolean	equals(Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of `Class` that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.
final void	wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait(long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.

From interface java.io.Closeable

From interface java.io.DataInput

abstract boolean	readBoolean() Reads a boolean.
abstract byte	readByte() Reads an 8-bit byte value.
abstract char	readChar() Reads a big-endian 16-bit character value.
abstract double	readDouble() Reads a big-endian 64-bit double value.
abstract float	readFloat() Reads a big-endian 32-bit float value.
abstract void	readFully(byte[] dst) Equivalent to `readFully(dst, 0, dst.length);`.
abstract void	readFully(byte[] dst, int offset, int byteCount) Reads `byteCount` bytes from this stream and stores them in the byte array `dst` starting at `offset`.
abstract int	readInt() Reads a big-endian 32-bit integer value.
abstract String	readLine() Returns a string containing the next line of text available from this stream.
abstract long	readLong() Reads a big-endian 64-bit long value.
abstract short	readShort() Reads a big-endian 16-bit short value.
abstract String	readUTF() Reads a string encoded with `modified UTF-8`.
abstract int	readUnsignedByte() Reads an unsigned 8-bit byte value and returns it as an int.
abstract int	readUnsignedShort() Reads a big-endian 16-bit unsigned short value and returns it as an int.
abstract int	skipBytes(int count) Skips `count` number of bytes.

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.

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.

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[] dst)

Since: API Level 1

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

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.

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

Since: API Level 1

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

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.

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

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.

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.

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.

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

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.

Results

Interfaces

Classes

Exceptions

Errors

ObjectInputStream

Class Overview

See Also

Summary

Public Constructors

public ObjectInputStream (InputStream input)

Parameters

Throws

Protected Constructors

protected ObjectInputStream ()

Throws

Public Methods

public int available ()

Returns

Throws

public void close ()

Throws

public void defaultReadObject ()

Throws

See Also

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

Parameters

Returns

Throws

public int read ()

Returns

Throws

public boolean readBoolean ()

Returns

Throws

public byte readByte ()

Returns

Throws

public char readChar ()

Returns

Throws

public double readDouble ()

Returns

Throws

public ObjectInputStream.GetField readFields ()

Returns

Throws

public float readFloat ()

Returns

Throws

public void readFully (byte[] dst)

Parameters

Throws

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

Parameters

Throws

public int readInt ()

Returns

Throws

public String readLine ()

Returns

Throws

public long readLong ()

Returns

Throws

public final Object readObject ()

Returns

Throws

See Also

public short readShort ()

Returns

Throws

public String readUTF ()

Returns

Throws

public Object readUnshared ()

Returns

Throws

See Also

public int readUnsignedByte ()