GigaSpaces XAP 9.7.2 API

net.jini.io
Class MarshalInputStream

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

GigaSpaces XAP 9.7.2 API

Copyright © GigaSpaces.