edu.rit.m2mi
Class Unihandle

java.lang.Object
  extended by edu.rit.m2mi.Handle
      extended by edu.rit.m2mi.Unihandle
All Implemented Interfaces:
Externalizable, Serializable

public class Unihandle
extends Handle

Class Unihandle is the base class for all M2MI unihandle objects. An actual unihandle class is a synthesized subclass of class Unihandle which implements the handle's target interface(s). Calling a target interface method on a unihandle object causes M2MI invocations to be performed on the target object to which the unihandle refers, namely, the object attached when the unihandle was created.

While instances of class Unihandle can be constructed, this is intended only for use during object serialization. When a synthesized unihandle is serialized into an object output stream, the synthesized unihandle replaces itself in the stream with an instance of class Unihandle containing the same EOID and target interface list. When an instance of class Unihandle is deserialized from an object input stream, the unihandle synthesizes the proper subclass, creates an instance of the synthesized subclass containing the same EOID and target interface list, and replaces itself with the subclass instance. In this way unihandle objects can be transported across the network without needing to transport the synthesized subclasses.

See Also:
Serialized Form

Field Summary
 
Fields inherited from class edu.rit.m2mi.Handle
myEoid, myInvocationFactory, myTargetInterface
 
Constructor Summary
Unihandle()
          Construct a new unihandle.
Unihandle(Eoid theEoid, Class theTargetInterface)
          Construct a new unihandle with the given EOID and target interface.
 
Method Summary
 void attach(Object theObject)
          Attach the given object to this unihandle.
 void detach()
          Detach the target object from this unihandle.
 boolean equals(Object theObject)
          Determine if this unihandle is equal to the given object.
 int hashCode()
          Returns a hash code for this unihandle.
 boolean invokes(Object theObject)
          Determine if a method invocation on this unihandle will be executed by the given object.
 Iterator iterator()
          Obtain an iterator for visiting the objects associated with this unihandle.
 void readExternal(ObjectInput theObjectInput)
          Read this unihandle from the given object input stream.
 String toString()
          Returns a string version of this unihandle.
 void writeExternal(ObjectOutput theObjectOutput)
          Write this unihandle to the given object output stream.
 
Methods inherited from class edu.rit.m2mi.Handle
getEoid, getInterface, getInterfaceName, isExportedEoid, isExportedInterface, iteratorEoid, iteratorInterface, setEoid, setInvocationFactory, setTargetInterface
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Unihandle

public Unihandle()
Construct a new unihandle. The EOID, target interface, and invocation factory are initially null.


Unihandle

public Unihandle(Eoid theEoid,
                 Class theTargetInterface)
Construct a new unihandle with the given EOID and target interface. The invocation factory is initially null.

Parameters:
theEoid - EOID.
theTargetInterface - Target interface list.
Method Detail

invokes

public boolean invokes(Object theObject)
Determine if a method invocation on this unihandle will be executed by the given object. Specifically, the following must all be true:
  1. theObject is not null.
  2. theObject is exported.
  3. theObject is the object attached to this unihandle.

Specified by:
invokes in class Handle
Parameters:
theObject - Object to test.
Returns:
True if a method invocation on this unihandle will be executed by theObject, false otherwise.
Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI layer is not initialized.

iterator

public Iterator iterator()
Obtain an iterator for visiting the objects associated with this unihandle. The returned iterator visits the objects, if any, in the local process that would be invoked by calling a method on this unihandle. The iterator() method takes a "snapshot" of the associated objects at the time it is called, and returns an iterator for the snapshot. Subsequently exporting or unexporting objects will have no effect on the returned iterator.

Specified by:
iterator in class Handle
Returns:
Iterator.

attach

public void attach(Object theObject)
Attach the given object to this unihandle. Afterwards, M2MI invocations on this unihandle will be executed by the given object instead of the formerly attached object. Also, M2MI invocations on an omnihandle for the target interface of this unihandle, or any superinterface thereof, will be executed by the given object. The formerly attached object remains exported and can still be invoked by any omnihandles, multihandles, and other unihandles that refer to it. If the given object is the one attached to this unihandle, attach() does nothing.

Parameters:
theObject - Object.
Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI layer is not initialized. Thrown if this unihandle is not attached to an object exported in the M2MI layer of the executing process.
NullPointerException - (unchecked exception) Thrown if theObject is null.
ClassCastException - (unchecked exception) Thrown if neither theObject's class nor any of its superclasses implements this unihandle's target interface.
ExportException - (unchecked exception) Thrown if there was a problem exporting the object.

detach

public void detach()
Detach the target object from this unihandle. Afterwards, M2MI invocations on this unihandle will no longer be executed by any object. The target object remains exported and can still be invoked by any omnihandles, multihandles, and other unihandles that refer to it. Once a unihandle is detached, the unihandle becomes unusable and you cannot later attach another object to it. If you need to do that, use a multihandle instead.

Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI layer is not initialized. Thrown if this unihandle is not attached to an object exported in the M2MI layer of the executing process.
ExportException - (unchecked exception) Thrown if there was a problem unexporting the object.

writeExternal

public void writeExternal(ObjectOutput theObjectOutput)
                   throws IOException
Write this unihandle to the given object output stream.

Specified by:
writeExternal in interface Externalizable
Overrides:
writeExternal in class Handle
Parameters:
theObjectOutput - Object output stream.
Throws:
IOException - Thrown if an I/O error occurred.

readExternal

public void readExternal(ObjectInput theObjectInput)
                  throws ClassNotFoundException,
                         IOException
Read this unihandle from the given object input stream. It assumes the stream was written by writeExternal().

Specified by:
readExternal in interface Externalizable
Overrides:
readExternal in class Handle
Parameters:
theObjectInput - Object input stream.
Throws:
ClassNotFoundException - Thrown if the class for an object being deserialized cannot be found.
IOException - Thrown if an I/O error occurred.

equals

public boolean equals(Object theObject)
Determine if this unihandle is equal to the given object. To be equal, the given object must be an instance of class Unihandle referring to the same target object as this unihandle; that is, with the same EOID as this unihandle.

Overrides:
equals in class Object
Parameters:
theObject - Object to test.
Returns:
True if this unihandle is equal to theObject, false otherwise.

hashCode

public int hashCode()
Returns a hash code for this unihandle.

Overrides:
hashCode in class Object

toString

public String toString()
Returns a string version of this unihandle.

Overrides:
toString in class Object


Copyright © 2001-2006 by Alan Kaminsky. All rights reserved. Send comments to ark­@­cs.rit.edu.