net.jini.io

Class MarshalledInstance

java.lang.Object

net.jini.io.MarshalledInstance

All Implemented Interfaces:

Serializable

public class MarshalledInstance
extends Object
implements Serializable

A MarshalledInstance contains an object in serialized form. The contained object can be deserialized on demand when explicitly requested. This allows an object to be sent from one VM to another in a way that allows the receiver to control when and if the object is deserialized.

The contained object is specified at construction time and can either be provided in unserialized or serialized form. If provided in unserialized form it will be serialized during construction with the serialization semantics defined by MarshalOutputStream. In particular, classes are annotated with a codebase URL from which the class can be loaded (if available).

If the MarshalledInstance needs to deserialize the contained object then the contained object will be deserialized with the deserialization semantics defined by MarshalInputStream. In particular, the codebase annotations associated with the contained object may be used to load classes referenced by the contained object.

MarshalledInstance provides functionality similar to java.rmi.MarshalledObject, but additionally provides for the verification of codebase integrity. Unlike java.rmi.MarshalledObject, it does not perform remote object-to-stub replacement.

Since:

2.0

Author:

Sun Microsystems, Inc.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static String	USE_GZIP_PROPERTY

Constructor Summary

Constructors

Constructor and Description
MarshalledInstance(MarshalledObject mo) Creates a new MarshalledInstance from an existing MarshalledObject.
MarshalledInstance(Object obj) Creates a new MarshalledInstance that contains the marshalled representation of the current state of the supplied object.
MarshalledInstance(Object obj, Collection context) Creates a new MarshalledInstance that contains the marshalled representation of the current state of the supplied object.

Method Summary

Modifier and Type	Method and Description
MarshalledObject	convertToMarshalledObject() Creates a new MarshalledObject that will contain an object equivalent to the object contained in this MarshalledInstance object.
boolean	equals(Object obj) Compares this MarshalledInstance to another object.
boolean	fullyEquals(Object obj) Compares this MarshalledInstance to another object.
Object	get(boolean verifyCodebaseIntegrity) Returns a new copy of the contained object.
Object	get(ClassLoader defaultLoader, boolean verifyCodebaseIntegrity, ClassLoader verifierLoader, Collection context) Returns a new copy of the contained object.
int	hashCode() Returns the hash code for this MarshalledInstance.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

USE_GZIP_PROPERTY

public static final String USE_GZIP_PROPERTY

See Also:

Constant Field Values

Constructor Detail

MarshalledInstance

public MarshalledInstance(Object obj)
                   throws IOException

Creates a new MarshalledInstance that contains the marshalled representation of the current state of the supplied object. The object is serialized with the semantics defined by MarshalOutputStream. The output stream used to marshal the object implements ObjectStreamContext and returns an empty collection from its getObjectStreamContext method.

Parameters:

obj - The Object to be contained in the new MarshalledInstance

Throws:

IOException - if the object cannot be serialized

MarshalledInstance

public MarshalledInstance(Object obj,
                          Collection context)
                   throws IOException

Creates a new MarshalledInstance that contains the marshalled representation of the current state of the supplied object. The object is serialized with the semantics defined by MarshalOutputStream. The output stream used to marshal the object implements ObjectStreamContext and returns the given collection from its getObjectStreamContext method.

Parameters:

obj - The Object to be contained in the new MarshalledInstance

context - the collection of context information objects

Throws:

IOException - if the object cannot be serialized

NullPointerException - if context is null

MarshalledInstance

public MarshalledInstance(MarshalledObject mo)

Creates a new MarshalledInstance from an existing MarshalledObject. An object equivalent to the object contained in the passed MarshalledObject will be contained in the new MarshalledInstance.

The object contained in the passed MarshalledObject will not be unmarshalled as part of this call.

Parameters:

mo - The MarshalledObject that contains the object the new MarshalledInstance should contain

Throws:

NullPointerException - if mo is null

Method Detail

convertToMarshalledObject

public MarshalledObject convertToMarshalledObject()

Creates a new MarshalledObject that will contain an object equivalent to the object contained in this MarshalledInstance object.

The object contained in this MarshalledInstance object will not be unmarshalled as part of this call.

Returns:

A new MarshalledObject which contains an object equivalent to the object contained in this MarshalledInstance

get

public Object get(boolean verifyCodebaseIntegrity)
           throws IOException,
                  ClassNotFoundException

Returns a new copy of the contained object. Deserialization is performed with the semantics defined by MarshalInputStream. The input stream used to unmarshal the object implements ObjectStreamContext and returns a collection from its getObjectStreamContext method which contains a single element of type IntegrityEnforcement; the integrityEnforced method of this element returns the specified verifyCodebaseIntegrity value.

MarshalledInstance implements this method by calling get(null, verifyCodebaseIntegrity, null, null).

Parameters:

verifyCodebaseIntegrity - if true then codebase integrity is verified, otherwise code base integrity is not verified

Returns:

a new copy of the contained object

Throws:

IOException - if an IOException occurs while deserializing the object from its internal representation

ClassNotFoundException - if any classes necessary for reconstructing the contained object can not be found or if verifyCodebaseIntegrity is true and the integrity of the contained object's codebase cannot be confirmed

get

public Object get(ClassLoader defaultLoader,
                  boolean verifyCodebaseIntegrity,
                  ClassLoader verifierLoader,
                  Collection context)
           throws IOException,
                  ClassNotFoundException

Returns a new copy of the contained object. Deserialization is performed with the semantics defined by MarshalInputStream. If context is not null the input stream used to unmarshal the object implements ObjectStreamContext and returns the given collection from its getObjectStreamContext method.

If context is null the input stream used to unmarshal the object implements ObjectStreamContext and returns a collection from its getObjectStreamContext method which contains a single element of type IntegrityEnforcement; the integrityEnforced method of this element returns the specified verifyCodebaseIntegrity value.

Parameters:

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

verifyCodebaseIntegrity - if true then codebase integrity is verified, otherwise code base integrity is not verified

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

context - the collection of context information objects or null

Returns:

a new copy of the contained object

Throws:

IOException - if an IOException occurs while deserializing the object from its internal representation

ClassNotFoundException - if any classes necessary for reconstructing the contained object can not be found or if verifyCodebaseIntegrity is true and the integrity of the contained object's codebase cannot be confirmed

fullyEquals

public boolean fullyEquals(Object obj)

Compares this MarshalledInstance to another object. Returns true if and only if the argument refers to an instance of MarshalledInstance that contains exactly the same serialized form for its contained object as this object does and has the same class codebase annotations.

Parameters:

obj - the object to compare with this MarshalledInstance

Returns:

true if the argument contains an object with an equivalent serialized form and codebase; otherwise returns false

equals

public boolean equals(Object obj)

Compares this MarshalledInstance to another object. Returns true if and only if the argument refers to an instance of MarshalledInstance that contains exactly the same serialized form for its contained object as this object does. The comparison ignores any class codebase annotations, so that two objects can be equivalent if they have the same serialized representation, except for the codebase of each class in the serialized representation.

Overrides:

equals in class Object

Parameters:

obj - the object to compare with this MarshalledInstance

Returns:

true if the argument contains an object with an equivalent serialized form; otherwise returns false

hashCode

public int hashCode()

Returns the hash code for this MarshalledInstance. The hash code is calculated only from the serialized form of the contained object.

Overrides:

hashCode in class Object

Returns:

The hash code for this object