edu.rit.m2mi
Class Multihandle

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

public class Multihandle
extends Handle

Class Multihandle is the base class for all M2MI multihandle objects. An actual multihandle class is a synthesized subclass of class Multihandle which implements the handle's target interface(s). Calling a target interface method on a multihandle object causes M2MI invocations to be performed on the target object or objects to which the multihandle refers, namely, all objects that have been attached to the multihandle.

While instances of class Multihandle can be constructed, this is intended only for use during object serialization. When a synthesized multihandle is serialized into an object output stream, the synthesized multihandle replaces itself in the stream with an instance of class Multihandle containing the same EOID and target interface list. When an instance of class Multihandle is deserialized from an object input stream, the multihandle 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 multihandle 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
Multihandle()
          Construct a new multihandle.
Multihandle(Eoid theEoid, Class theTargetInterface)
          Construct a new multihandle with the given EOID and target interface.
 
Method Summary
 void attach(Object theObject)
          Attach the given object to this multihandle.
 void detach(Object theObject)
          Detach the given object from this multihandle.
 boolean equals(Object theObject)
          Determine if this multihandle is equal to the given object.
 int hashCode()
          Returns a hash code for this multihandle.
 boolean invokes(Object theObject)
          Determine if a method invocation on this multihandle will be executed by the given object.
 Iterator iterator()
          Obtain an iterator for visiting the objects associated with this multihandle.
 void readExternal(ObjectInput theObjectInput)
          Read this multihandle from the given object input stream.
 String toString()
          Returns a string version of this multihandle.
 void writeExternal(ObjectOutput theObjectOutput)
          Write this multihandle 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

Multihandle

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


Multihandle

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

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

invokes

public boolean invokes(Object theObject)
Determine if a method invocation on this multihandle 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 has been attached to this multihandle.

Specified by:
invokes in class Handle
Parameters:
theObject - Object to test.
Returns:
True if a method invocation on this multihandle 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 multihandle. The returned iterator visits the objects, if any, in the local process that would be invoked by calling a method on this multihandle. 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 multihandle. Afterwards, M2MI invocations on this multihandle will be executed by the given object (as well as any other objects attached to this multihandle). Also, M2MI invocations on an omnihandle for the target interface of this multihandle, or any superinterface thereof, will be executed by the given object. If the given object is already attached to this multihandle, attach() does nothing.

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

detach

public void detach(Object theObject)
Detach the given object from this multihandle. Afterwards, M2MI invocations on this multihandle will no longer be executed by the given object. The given object remains exported and can still be invoked by any omnihandles, unihandles, and other multihandles that refer to it. If the given object is not attached to this multihandle, detach() does nothing.

Parameters:
theObject - Object.
Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI layer is not initialized.
NullPointerException - (unchecked exception) Thrown if theObject is null.
ExportException - (unchecked exception) Thrown if there was a problem unexporting the object.

writeExternal

public void writeExternal(ObjectOutput theObjectOutput)
                   throws IOException
Write this multihandle 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 multihandle 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 multihandle is equal to the given object. To be equal, the given object must be an instance of class Multihandle referring to the same set of target objects as this multihandle; that is, with the same EOID as this multihandle.

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

hashCode

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

Overrides:
hashCode in class Object

toString

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

Overrides:
toString in class Object


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