Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.jini.io
Class MarshalInputStream

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

All Implemented Interfaces:
  DataInput, ObjectInput, ObjectStreamConstants, ObjectStreamContext

public class MarshalInputStream
extends ObjectInputStream
implements ObjectStreamContext

An extension of `ObjectInputStream` that implements the dynamic class loading semantics of 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

Nested Class Summary

Nested classes 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_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_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(TM) 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`.

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

  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved