edu.rit.m2mi
Class Invocation

java.lang.Object
  extended by edu.rit.m2mi.Invocation
All Implemented Interfaces:
Externalizable, Serializable
Direct Known Subclasses:
MultiInvocation, OmniInvocation, UniInvocation

public abstract class Invocation
extends Object
implements Externalizable

Class Invocation is the abstract base class for all invocation objects in M2MI.

When a method is invoked on a handle, the handle creates an invocation object of the proper kind and hands the invocation object off to the M2MI Layer. The invocation object contains the following information:

The M2MI Layer uses the invocation object to find all the locally-exported target objects that need to perform the invocation, and to actually do the invocations on those target objects. The M2MI Layer also broadcasts the invocation object by sending it in an M2MP message -- an M2MI invocation message is just a message prefix followed by a serialized invocation object. When some other process's M2MI Layer receives an M2MI invocation message, the M2MI Layer deserializes the invocation object, then uses the invocation object to actually do the invocations.

Subclasses of class Invocation define the behavior for these two aspects:

Note: Class Invocation is multiple thread safe.

See Also:
Serialized Form

Field Summary
protected  Eoid myEoid
          Exported object identifier.
protected  MethodDescriptor myMethodDescriptor
          Method descriptor.
protected  MethodInvoker myMethodInvoker
          Method invoker.
protected  Iterator myTargetObjects
          Iterator for visiting all the target objects.
 
Constructor Summary
Invocation()
          Construct a new invocation object.
Invocation(Eoid theEoid, MethodDescriptor theMethodDescriptor, MethodInvoker theMethodInvoker)
          Construct a new invocation object with the given EOID, method descriptor, and method invoker.
 
Method Summary
protected abstract  byte[] getMessagePrefix()
          Obtain the M2MP message prefix corresponding to this invocation object.
protected abstract  Iterator getTargetObjects()
          Determine the target objects that this invocation object will invoke.
 void invoke(Object theTargetObject)
          Perform the invocation specified by this invocation object's method invoker on the given target object.
 Object nextTargetObject()
          Obtain the next target object that this invocation will invoke.
abstract  void processFromHandle()
          Process this invocation, assuming it was created as a result of calling a method on a handle.
abstract  void processFromMessage()
          Process this invocation, assuming it was created from an incoming M2MI message.
 void readExternal(ObjectInput theObjectInput)
          Read this invocation object from the given object input stream.
 String toString()
          Returns a string version of this invocation object.
 void writeExternal(ObjectOutput theObjectOutput)
          Write this invocation object to the given object output stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

myEoid

protected Eoid myEoid
Exported object identifier.


myMethodDescriptor

protected MethodDescriptor myMethodDescriptor
Method descriptor.


myMethodInvoker

protected MethodInvoker myMethodInvoker
Method invoker.


myTargetObjects

protected Iterator myTargetObjects
Iterator for visiting all the target objects.

Constructor Detail

Invocation

public Invocation()
Construct a new invocation object. The invocation object's EOID, method descriptor, and method invoker are initialized to null. Their values must be filled in by calling the readExternal() method.


Invocation

public Invocation(Eoid theEoid,
                  MethodDescriptor theMethodDescriptor,
                  MethodInvoker theMethodInvoker)
Construct a new invocation object with the given EOID, method descriptor, and method invoker.

Parameters:
theEoid - EOID.
theMethodDescriptor - Method descriptor.
theMethodInvoker - Method invoker.
Throws:
NullPointerException - (unchecked exception) Thrown if any argument is null.
Method Detail

writeExternal

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

Specified by:
writeExternal in interface Externalizable
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 invocation object from the given object input stream. It assumes the stream was written by writeExternal().

Specified by:
readExternal in interface Externalizable
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.

processFromHandle

public abstract void processFromHandle()
Process this invocation, assuming it was created as a result of calling a method on a handle. This method goes to the M2MI Layer to broadcast this invocation in an outgoing M2MI message if necessary, and to invoke any target objects exported in the M2MI Layer if necessary.

Throws:
InvocationException - (unchecked exception) Thrown if there was a problem processing the invocation.

processFromMessage

public abstract void processFromMessage()
Process this invocation, assuming it was created from an incoming M2MI message. This method goes to the M2MI Layer to invoke any target objects exported in the M2MI Layer.

Throws:
InvocationException - (unchecked exception) Thrown if there was a problem processing the invocation.

nextTargetObject

public Object nextTargetObject()
Obtain the next target object that this invocation will invoke. If this is the first call, nextTargetObject() calls getTargetObjects() to get the target objects. If there are no more target objects to invoke, nextTargetObject() returns null.

Returns:
Target object, or null if there are no more target objects.

invoke

public void invoke(Object theTargetObject)
Perform the invocation specified by this invocation object's method invoker on the given target object. The target object's class must implement this invocation object's target interface. This invocation object's target method is invoked on the target object, passing in this invocation object's argument values.

Parameters:
theTargetObject - Target object.
Throws:
NullPointerException - (unchecked exception) Thrown if theTargetObject is null.
ClassCastException - (unchecked exception) Thrown if theTargetObject is not an instance of this invocation object's target interface.

toString

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

Overrides:
toString in class Object

getMessagePrefix

protected abstract byte[] getMessagePrefix()
Obtain the M2MP message prefix corresponding to this invocation object. This method goes to the M2MI Layer to determine the appropriate message prefix.

Returns:
Message prefix.

getTargetObjects

protected abstract Iterator getTargetObjects()
Determine the target objects that this invocation object will invoke. This method goes to the M2MI Layer to determine the appropriate target objects.

Returns:
Iterator for visiting all the target objects.


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