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

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.

Since:

Android 1.0

See Also:

ObjectOutputStream, ObjectInput, Serializable, Externalizable

Nested Class Summary

static class	ObjectInputStream.GetField GetField is an inner class that provides access to the persistent fields read from the source stream.
(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 that reads from the InputStream input.

Method Summary

int	available() Returns the number of bytes of primitive data that can be read from this stream without blocking.
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 offset, int length) Reads at most length bytes from the source stream and stores them in byte array buffer starting at offset count.
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[] buffer) Reads bytes from the source stream into the byte array buffer.
void	readFully(byte[] buffer, int offset, int length) Reads bytes from the source stream into the byte array buffer.
int	readInt() Reads an integer (32 bit) from the source stream.
String	readLine() Deprecated. Use BufferedReader
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 overriden 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, 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. 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.

Since:

Android 1.0

See Also:

SecurityManager.checkPermission(java.security.Permission)

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.

SecurityException - if a security manager is installed and it denies subclassing this class.

Since:

Android 1.0

Method Detail

available

public int available()
              throws IOException

Returns the number of bytes of primitive data that can be read from this stream without blocking. This method should not be used at any arbitrary position; just when reading primitive data types (int, char etc).

Specified by:

available in interface ObjectInput

Overrides:

available in class InputStream

Returns:

the number of available primitive data bytes.

Throws:

IOException - if any I/O problem occurs while computing the available bytes.

Since:

Android 1.0

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

Overrides:

close in class InputStream

Throws:

IOException - if an error occurs while closing this stream.

Since:

Android 1.0

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

Since:

Android 1.0

See Also:

ObjectOutputStream.defaultWriteObject()

enableResolveObject

protected boolean enableResolveObject(boolean enable)
                               throws SecurityException

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.

Since:

Android 1.0

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.

Since:

Android 1.0

read

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

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.

Specified by:

read in interface ObjectInput

Overrides:

read in class InputStream

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

See Also:

DataOutput.writeFloat(float)

readFully

public void readFully(byte[] buffer)
               throws IOException

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

Specified by:

readFully in interface DataInput

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.

Since:

Android 1.0

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

Since:

Android 1.0

See Also:

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

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.

Since:

Android 1.0

See Also:

DataOutput.writeInt(int)

readLine

@Deprecated
public String readLine()
                throws IOException

Deprecated. Use BufferedReader

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0

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.

Since:

Android 1.0