net.jini.io
Class MarshalInputStream

java.lang.Object
  java.io.InputStream
      java.io.ObjectInputStream
          net.jini.io.MarshalInputStream

All Implemented Interfaces:

Closeable, DataInput, ObjectInput, ObjectStreamConstants, ObjectStreamContext

public class MarshalInputStream
extends ObjectInputStream
implements ObjectStreamContext

An extension of ObjectInputStream that implements the dynamic class loading semantics of Java(TM) Remote Method Invocation (Java RMI) argument and result unmarshalling (using RMIClassLoader). A MarshalInputStream is intended to read data written by a corresponding MarshalOutputStream.

MarshalInputStream implements the input side of the dynamic class loading semantics by overriding resolveClass and resolveProxyClass to resolve class descriptors in the stream using ClassLoading.loadClass and ClassLoading.loadProxyClass (which, in turn, use RMIClassLoader.loadClass and RMIClassLoader.loadProxyClass), optionally with codebase annotation strings written by a MarshalOutputStream.

By default, a MarshalInputStream ignores all codebase annotation strings, instead using a codebase value of null when loading classes. Codebase annotation strings will only be used by a MarshalInputStream after its useCodebaseAnnotations method has been invoked.

MarshalInputStream supports optional verification that all codebase annotation URLs that are used to load classes resolved by the stream provide content integrity (see Security.verifyCodebaseIntegrity). Whether or not a particular MarshalInputStream instance verifies that codebase annotation URLs provide content integrity is determined by the verifyCodebaseIntegrity constructor argument. See ClassLoading.loadClass and ClassLoading.loadProxyClass for details of how codebase integrity verification is performed.

MarshalInputStream reads class annotations from its own stream; a subclass can override the readAnnotation method to read the class annotations from a different location.

A MarshalInputStream is not guaranteed to be safe for concurrent use by multiple threads.

Since:

2.0

Author:

Sun Microsystems, Inc.

Nested Class Summary

Nested classes/interfaces inherited from class java.io.ObjectInputStream

ObjectInputStream.GetField

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

MarshalInputStream(InputStream in, ClassLoader defaultLoader, boolean verifyCodebaseIntegrity, ClassLoader verifierLoader, Collection context)
Creates a new MarshalInputStream that reads marshalled data from the specified underlying InputStream.

Method Summary

Collection	getObjectStreamContext() Returns the collection of context information objects that was passed to this stream's constructor.
protected String	readAnnotation() Reads and returns a class annotation string value (possibly null) that was written by a corresponding MarshalOutputStream implementation.
protected Class	resolveClass(ObjectStreamClass classDesc) Resolves the appropriate Class object for the stream class descriptor classDesc.
protected Class	resolveProxyClass(String[] interfaceNames) Resolves the appropriate Class object for the proxy class described by the interface names interfaceNames.
void	useCodebaseAnnotations() Enables the use of codebase annotation strings written by the corresponding MarshalOutputStream.

Methods inherited from class java.io.ObjectInputStream

available, close, defaultReadObject, enableResolveObject, read, read, readBoolean, readByte, readChar, readClassDescriptor, readDouble, readFields, readFloat, readFully, readFully, readInt, readLine, readLong, readObject, readObjectOverride, readShort, readStreamHeader, readUnshared, readUnsignedByte, readUnsignedShort, readUTF, registerValidation, resolveObject, skipBytes

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

MarshalInputStream

public MarshalInputStream(InputStream in,
                          ClassLoader defaultLoader,
                          boolean verifyCodebaseIntegrity,
                          ClassLoader verifierLoader,
                          Collection context)
                   throws IOException

Creates a new MarshalInputStream that reads marshalled data from the specified underlying InputStream.

This constructor passes in to the superclass constructor that has an InputStream parameter.

defaultLoader will be passed as the defaultLoader argument to ClassLoading.loadClass and ClassLoading.loadProxyClass whenever those methods are invoked by resolveClass and resolveProxyClass.

If verifyCodebaseIntegrity is true, then the created stream will verify that all codebase annotation URLs that are used to load classes resolved by the stream provide content integrity, and whenever Security.verifyCodebaseIntegrity is invoked to enforce that verification, verifierLoader will be passed as the loader argument. See ClassLoading.loadClass and ClassLoading.loadProxyClass for details of how codebase integrity verification is performed.

context will be used as the return value of the created stream's getObjectStreamContext method.

Parameters:

in - the input stream to read marshalled data from

defaultLoader - the class loader value (possibly null) to pass as the defaultLoader argument to ClassLoading methods

verifyCodebaseIntegrity - if true, this stream will verify that codebase annotation URLs used to load classes resolved by this stream provide content integrity

verifierLoader - the class loader value (possibly null) to pass to Security.verifyCodebaseIntegrity, if verifyCodebaseIntegrity is true

context - the collection of context information objects to be returned by this stream's getObjectStreamContext method

Throws:

IOException - if the superclass's constructor throws an IOException

SecurityException - if the superclass's constructor throws a SecurityException

NullPointerException - if in or context is null

Method Detail

useCodebaseAnnotations

public void useCodebaseAnnotations()

Enables the use of codebase annotation strings written by the corresponding MarshalOutputStream.

If this method has not been invoked on this stream, then the resolveClass and resolveProxyClass methods ignore the class annotation strings and just use a null codebase value when loading classes. After this method has been invoked, then the resolveClass and resolveProxyClass methods use the class annotation strings as codebase values.

getObjectStreamContext

public Collection getObjectStreamContext()

Returns the collection of context information objects that was passed to this stream's constructor.

Specified by:

getObjectStreamContext in interface ObjectStreamContext

Returns:

a collection of this stream's context objects

resolveClass

protected Class resolveClass(ObjectStreamClass classDesc)
                      throws IOException,
                             ClassNotFoundException

Resolves the appropriate Class object for the stream class descriptor classDesc.

MarshalInputStream implements this method as follows:

This method first invokes this stream's readAnnotation method to read the annotation string value (possibly null) for the class descriptor. If readAnnotation throws an exception, then this method throws that exception. Otherwise, a codebase value is chosen as follows: if the useCodebaseAnnotations method has been invoked on this stream, then the codebase value chosen is the value that was returned by readAnnotation; otherwise, the codebase value chosen is null.

This method then invokes ClassLoading.loadClass with the chosen codebase value as the first argument, the name of the class described by classDesc as the second argument, and the defaultLoader, verifyCodebaseIntegrity, and verifierLoader values that were passed to this stream's constructor as the third, fourth, and fifth arguments. If ClassLoading.loadClass throws a ClassNotFoundException and the name of the class described by classDesc equals the Java programming language keyword for a primitive type or void, then this method returns the Class corresponding to that primitive type or void (Integer.TYPE for int, Void.TYPE for void, and so forth). Otherwise, if ClassLoading.loadClass throws an exception, this method throws that exception, and if it returns normally, this method returns the Class returned by ClassLoading.loadClass.

Overrides:

resolveClass in class ObjectInputStream

Parameters:

classDesc - the stream class descriptor to resolve

Returns:

the resolved class

Throws:

IOException - if readAnnotation throws an IOException, or if ClassLoading.loadClass throws a MalformedURLException

ClassNotFoundException - if readAnnotation or ClassLoading.loadClass throws a ClassNotFoundException

NullPointerException - if classDesc is null

resolveProxyClass

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

Resolves the appropriate Class object for the proxy class described by the interface names interfaceNames.

MarshalInputStream implements this method as follows:

This method first invokes this stream's readAnnotation method to read the annotation string value (possibly null) for the class descriptor. If readAnnotation throws an exception, then this method throws that exception. Otherwise, a codebase value is chosen as follows: if the useCodebaseAnnotations method has been invoked on this stream, then the codebase value chosen is the value that was returned by readAnnotation; otherwise, the codebase value chosen is null.

This method then invokes ClassLoading.loadProxyClass with the chosen codebase value as the first argument, interfaceNames as the second argument, and the defaultLoader, verifyCodebaseIntegrity, and verifierLoader values that were passed to this stream's constructor as the third, fourth, and fifth arguments. If ClassLoading.loadProxyClass throws an exception, then this method throws that exception. Otherwise, this method returns the Class returned by ClassLoading.loadProxyClass.

Overrides:

resolveProxyClass in class ObjectInputStream

Parameters:

interfaceNames - the list of interface names that were deserialized in the proxy class descriptor

Returns:

the resolved dynamic proxy class

Throws:

IOException - if readAnnotation throws an IOException, or if ClassLoading.loadProxyClass throws a MalformedURLException

ClassNotFoundException - if readAnnotation or ClassLoading.loadProxyClass throws a ClassNotFoundException

NullPointerException - if interfaceNames is null or if any element of interfaceNames is null

readAnnotation

protected String readAnnotation()
                         throws IOException,
                                ClassNotFoundException

Reads and returns a class annotation string value (possibly null) that was written by a corresponding MarshalOutputStream implementation.

MarshalInputStream implements this method to just read the annotation value from this stream using readObject, and if readObject returns a non-null value that is not a String, an InvalidObjectException is thrown.

A subclass can override this method to read the annotation from a different location.

Returns:

the class annotation string value read (possibly null)

Throws:

IOException - if an I/O exception occurs reading the annotation

ClassNotFoundException - if a ClassNotFoundException occurs reading the annotation