edu.rit.m2mi
Class M2MI

java.lang.Object
  extended by edu.rit.m2mi.M2MI

public class M2MI
extends Object

Class M2MI encapsulates the M2MI Layer. An M2MI-based client program only has to use the static methods in class M2MI and the methods in classes Handle, Omnihandle, Multihandle, and Unihandle. The client should not use directly the other classes in package edu.rit.m2mi.

The client program must call one (and only one) of the initialize() methods to configure the M2MI Layer before calling any other method. Typically the no-argument initialize() method is called. Additional initialize() methods are provided for tailoring the class loader used to load the M2MI Layer's synthesized handle and method invoker classes (see class M2MIClassLoader for further information). Various parameters for configuring the M2MI Layer are obtained from the M2MI properties file (see class M2MIProperties for further information).


Method Summary
static void export(Object theObject, Class theInterface)
          Export the given object with the given target interface.
static M2MIClassLoader getClassLoader()
          Returns the M2MI Layer's class loader.
static Multihandle getMultihandle(Class theInterface)
          Obtain a multihandle for the given target interface.
static Omnihandle getOmnihandle(Class theInterface)
          Obtain an omnihandle for the given target interface.
static Unihandle getUnihandle(Object theObject, Class theInterface)
          Obtain a unihandle for the given target interface, attached to the given object.
static void initialize()
          Initialize the M2MI Layer.
static void initialize(ClassLoader theParent)
          Initialize the M2MI Layer.
static void initialize(ClassLoader theParent, ProtectionDomain theProtectionDomain)
          Initialize the M2MI Layer.
static void initialize(ProtectionDomain theProtectionDomain)
          Initialize the M2MI Layer.
static void unexport(Object theObject)
          Unexport the given object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

initialize

public static void initialize()
Initialize the M2MI Layer. One of the initialize() methods must be called before calling any other M2MI method. The system class loader is used as the parent class loader for the M2MI Layer's class loader. The protection domain of class M2MIClassLoader will be associated with all synthesized handle and method invoker classes. Other parameters used to configure the M2MI Layer are obtained from the M2MI properties file.

Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI Layer cannot be initialized.
SecurityException - (unchecked exception) Thrown if there is a security manager and it doesn't allow creation of a new class loader or it doesn't allow obtaining the protection domain of class M2MIClassLoader.

initialize

public static void initialize(ClassLoader theParent)
Initialize the M2MI Layer. One of the initialize() methods must be called before calling any other M2MI method. The given class loader is used as the parent class loader for the M2MI Layer's class loader. The protection domain of class M2MIClassLoader will be associated with all synthesized handle and method invoker classes. Other parameters used to configure the M2MI Layer are obtained from the M2MI properties file.

Parameters:
theParent - Parent class loader for delegation.
Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI Layer cannot be initialized.
SecurityException - (unchecked exception) Thrown if there is a security manager and it doesn't allow creation of a new class loader or it doesn't allow obtaining the protection domain of class M2MIClassLoader.

initialize

public static void initialize(ProtectionDomain theProtectionDomain)
Initialize the M2MI Layer. One of the initialize() methods must be called before calling any other M2MI method. The system class loader is used as the parent class loader for the M2MI Layer's class loader. The given protection domain will be associated with all synthesized handle and method invoker classes. Other parameters used to configure the M2MI Layer are obtained from the M2MI properties file.

Parameters:
theProtectionDomain - Protection domain for all handle and method invoker classes.
Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI Layer cannot be initialized.
SecurityException - (unchecked exception) Thrown if there is a security manager and it doesn't allow creation of a new class loader.

initialize

public static void initialize(ClassLoader theParent,
                              ProtectionDomain theProtectionDomain)
Initialize the M2MI Layer. One of the initialize() methods must be called before calling any other M2MI method. The given class loader is used as the parent class loader for the M2MI Layer's class loader. The given protection domain will be associated with all synthesized handle and method invoker classes. Other parameters used to configure the M2MI Layer are obtained from the M2MI properties file.

Parameters:
theParent - Parent class loader for delegation.
theProtectionDomain - Protection domain for all handle and method invoker classes.
Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI Layer cannot be initialized.
SecurityException - (unchecked exception) Thrown if there is a security manager and it doesn't allow creation of a new class loader.

export

public static void export(Object theObject,
                          Class theInterface)
Export the given object with the given target interface. Afterwards, M2MI invocations on an omnihandle for the target interface or any superinterface thereof will be executed by the given object.

Note: The same object can be exported multiple times with different target interfaces.

Parameters:
theObject - Object.
theInterface - Target interface.
Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI Layer is not initialized.
NullPointerException - (unchecked exception) Thrown if theObject is null or theInterface is null.
ClassCastException - (unchecked exception) Thrown if theObject is not an instance of the target interface.
InvalidMethodException - (unchecked exception) Thrown if the target interface is a class rather than an interface, if any method in the target interface returns a value, or if any method in the target interface throws any checked exceptions.
SynthesisException - (unchecked exception) Thrown if there was a problem synthesizing or loading the requisite omnihandle class. (The omnihandle class is not instantiated.)
ExportException - (unchecked exception) Thrown if there was a problem exporting the object.

unexport

public static void unexport(Object theObject)
Unexport the given object. Afterwards, M2MI invocations on all omnihandles, unihandles, and multihandles that formerly referred to the given object, will no longer be executed by the given object. If the given object was not exported in the M2MI Layer, unexport() 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.

getOmnihandle

public static Omnihandle getOmnihandle(Class theInterface)
Obtain an omnihandle for the given target interface. The omnihandle implements the target interface and can be cast to the target interface (or any superinterface thereof).

Parameters:
theInterface - Target interface.
Returns:
Omnihandle for theInterface.
Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI layer is not initialized.
NullPointerException - (unchecked exception) Thrown if theInterface is null.
InvalidMethodException - (unchecked exception) Thrown if the target interface is a class rather than an interface, if any method in the target interface returns a value, or if any method in the target interface throws any checked exceptions.
SynthesisException - (unchecked exception) Thrown if there was a problem synthesizing, loading, or instantiating the omnihandle class.

getMultihandle

public static Multihandle getMultihandle(Class theInterface)
Obtain a multihandle for the given target interface. The multihandle implements the target interface and can be cast to the target interface (or any superinterface thereof). Initially, no objects are attached to the multihandle. Use the attach() and detach() methods in class Multihandle to attach objects to and detach objects from the multihandle.

Parameters:
theInterface - Target interface.
Returns:
Multihandle for theInterface.
Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI layer is not initialized.
NullPointerException - (unchecked exception) Thrown if theInterface is null.
InvalidMethodException - (unchecked exception) Thrown if the target interface is a class rather than an interface, if any method in the target interface returns a value, or if any method in the target interface throws any checked exceptions.
SynthesisException - (unchecked exception) Thrown if there was a problem synthesizing, loading, or instantiating the multihandle class.

getUnihandle

public static Unihandle getUnihandle(Object theObject,
                                     Class theInterface)
Obtain a unihandle for the given target interface, attached to the given object. The unihandle implements the target interface and can be cast to the target interface (or any superinterface thereof). Afterwards, M2MI invocations on the returned unihandle, and M2MI invocations on an omnihandle for the target interface or any superinterface thereof, will be executed by the given object.

Note: Multiple unihandles, with different target interfaces, can be created and attached to the same object.

Parameters:
theObject - Object.
theInterface - Target interface.
Returns:
Unihandle for theObject.
Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI layer is not initialized.
NullPointerException - (unchecked exception) Thrown if theObject is null or theInterface is null.
ClassCastException - (unchecked exception) Thrown if theObject is not an instance of the target interface.
InvalidMethodException - (unchecked exception) Thrown if the target interface is a class rather than an interface, if any method in the target interface returns a value, or if any method in the target interface throws any checked exceptions.
SynthesisException - (unchecked exception) Thrown if there was a problem synthesizing, loading, or instantiating the unihandle class.
ExportException - (unchecked exception) Thrown if there was a problem exporting the object.

getClassLoader

public static M2MIClassLoader getClassLoader()
Returns the M2MI Layer's class loader. The class loader is used to load all the synthesized handle classes and method invoker classes.

Throws:
IllegalStateException - (unchecked exception) Thrown if the M2MI Layer is not initialized.


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