net.jini.io

Class MarshalledInstance

java.lang.Object

net.jini.io.MarshalledInstance

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

AtomicMarshalledInstance

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

Constructor Summary

Constructors

Modifier	Constructor and Description
	MarshalledInstance(AtomicSerial.GetArg arg)
	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.
protected	MarshalledInstance(Object obj, Collection context, MarshalFactory marshalFactory) 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.
protected MarshalFactory	getMarshalFactory() Sub classes implement this method to use alternative Serialization frameworks to unmarshall data.
int	hashCode() Returns the hash code for this MarshalledInstance.
boolean	isNull() Null reference check for marshaled instance.

Methods inherited from class java.lang.Object

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

Constructor Detail

MarshalledInstance

public MarshalledInstance(AtomicSerial.GetArg arg)
                   throws IOException

Throws:

IOException

MarshalledInstance

protected MarshalledInstance(Object obj,
                             Collection context,
                             MarshalFactory marshalFactory)
                      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 MarshalOutput. This is designed to allow MarshalledInstance to be extensible and utilize other Serialization Frameworks. This constructor calls a chain of internal constructors and static methods that prevent finalizer attacks. It is advisable for overriding classes to be stateless.

Parameters:

obj - The Object to be contained in the new MarshalledInstance

context - the collection of context information objects or null

marshalFactory - MarshalFactory used to create underlying MarshalInstanceInput and MarshalInstanceOutput.

Throws:

IOException - if the object cannot be serialized

NullPointerException - if context or marshalFactory is null.

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.

Subclasses may override getMarshalFactory() to customize the semantics of serialization.

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.

Some Objects in the Jini api include MarshalledObject as part of their serial form.

Returns:

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

getMarshalFactory

protected MarshalFactory getMarshalFactory()

Sub classes implement this method to use alternative Serialization frameworks to unmarshall data.

Returns:

a new MarshalFactory instance.

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

Subclasses should not override this method.

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

Since:

3.1.0 MarshalledInstance is extensible and since it is used for hand-back objects over remote connections and because it's possible for MarshalledInstance to be converted to MarshalledObject and back again to MarshalledInstance, the resulting conversion may loose type compatibility with the original instance which may be a subclass of MarshalledInstance. This equals method allows a caller to determine if the hand-back instance is equal to the original, based solely on the serial form of the contained object.

hashCode

public final int hashCode()

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

Subclasses should not override this method.

Overrides:

hashCode in class Object

Returns:

The hash code for this object

isNull

public final boolean isNull()

Null reference check for marshaled instance.

Returns:

true if MarshalledInstance contains a null reference.