Build 1.0_r1(from source)

java.io
Class ObjectInputStream

java.lang.Object
  extended by java.io.InputStream
      extended by 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.

Build 1.0_r1(from source)

Please submit a feedback, bug or feature