edu.emory.mathcs.rmix
Class Rmix

java.lang.Object
  edu.emory.mathcs.rmix.Rmix

public class Rmix

extends java.lang.Object

This class provides a facade through which most of the client-side RMIX API is exposed. The API has a set of methods to export remote objects (creating server references) and to create remote stubs by binding to remote references obtained for that server references. The API also enables management of RMIX providers, allowing to explicitly load and unload them at run time. Additionally, methods are provided to generate and compare globally unique object identifiers.

Version:

1.1

Author:

Dawid Kurzyniec

Nested Class Summary

static interface	Rmix.Binder Entity capable of binding (creating stubs for) remote references.
static class	Rmix.ClientContext Invocation context at the client side as represented by the stub on which remote call was invoked.
static interface	Rmix.Context Represents the RMIX context of the current operation.
static interface	Rmix.Executor
static interface	Rmix.Exporter Entity capable of exporting remote objects.
static interface	Rmix.Future
static class	Rmix.GetClassLoaderForExportAction Providers should use the class loader returned by this method for remote method dispatch on the target object.
static class	Rmix.LocalInvocationContext Used by RMIX providers that wish to support local bindings.
static class	Rmix.ProviderHook Handle handed out to RMIX providers that allows them to interoperate with RMIX framework.
static class	Rmix.ServerContext Invocation context at the server side as represented by the server reference on which remote call is dispatched, and the information about the transport.

Method Summary

static java.rmi.Remote	bind(RemoteRef remoteRef) Creates dynamic proxy for a given remote reference using default bind properties.
static java.rmi.Remote	bind(RemoteRef remoteRef, Parameters bindParams, java.lang.ClassLoader cloader, boolean resolveAll) Creates dynamic proxy for a given remote reference using specified bind parameters and a given class loader.
static java.lang.String	defaultProtocol() Gets the name of the default RMIX protocol.
static java.lang.String	defaultProvider() Gets the name of the default RMIX provider.
static ServerRef	export(InvocationTarget target) Exports the remote object using default export properties.
static ServerRef	export(InvocationTarget target, ServerRef context) Exports the remote object using export properties from a given context server reference.
static ServerRef	export(InvocationTarget target, java.lang.String protocol, Parameters exportParams) Exports the remote object specified as the invocation target using specified protocol and parameters.
static ServerRef	export(InvocationTarget target, java.lang.String protocol, java.lang.String provider, Parameters exportParams) Exports the remote object specified as the invocation target using specified RMIX protocol, provider and parameters.
static ServerRef	export(java.rmi.Remote target) Exports the remote object using default export properties.
static ServerRef	export(java.rmi.Remote target, ServerRef context) Exports the remote object using export properties from a given context server reference.
static ServerRef	export(java.rmi.Remote target, java.lang.String protocol, Parameters exportParams) Exports the remote object using specified protocol and parameters.
static ServerRef	export(java.rmi.Remote target, java.lang.String protocol, java.lang.String provider, Parameters exportParams) Exports the remote object using specified protocol, provider and parameters.
static Rmix.ClientContext	getClientContext() During remote call processing on the client side, returns the current RMIX client context; otherwise, returns null.
static ObjGUID	getObjGUID(java.lang.Object obj) Returns unique identifier (ObjGUID) associated with a given object.
static java.util.Properties	getRmixConfiguration()
static java.lang.String	getRmixConfigurationProperty(java.lang.String name)
static java.lang.String	getRmixConfigurationProperty(java.lang.String name, java.lang.String defVal)
static Rmix.ServerContext	getServerContext() During remote call dispatch on the server side, returns the current RMIX server context; otherwise, returns null.
static ObjGUID	getTargetGUID(java.lang.Object obj) Returns unique identifier (ObjGUID) associated with the given remote object.
static java.lang.String[]	listProtocols()
static java.lang.String[]	listProviders()
static java.rmi.Remote	wrap(java.rmi.Remote target) Creates serializable dynamic proxy for a given target object with a default protocol service provider, using current thread's context class loader and resolving all interfaces.
static java.rmi.Remote	wrap(java.rmi.Remote target, java.lang.String protocol) Creates serializable dynamic proxy for a given target object with specified protocol service provider, using current thread's context class loader and resolving all interfaces.
static java.rmi.Remote	wrap(java.rmi.Remote target, java.lang.String protocol, java.lang.ClassLoader cloader, boolean resolveAll) Creates serializable dynamic proxy for a given target object with specified protocol service provider and using specified class loader.

Methods inherited from class java.lang.Object

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

Method Detail

getRmixConfiguration

public static java.util.Properties getRmixConfiguration()

getRmixConfigurationProperty

public static java.lang.String getRmixConfigurationProperty(java.lang.String name)

getRmixConfigurationProperty

public static java.lang.String getRmixConfigurationProperty(java.lang.String name,
                                                            java.lang.String defVal)

listProviders

public static java.lang.String[] listProviders()

listProtocols

public static java.lang.String[] listProtocols()

getObjGUID

public static ObjGUID getObjGUID(java.lang.Object obj)

Returns unique identifier (ObjGUID) associated with a given object. This method is guaranteed to return the same ObjGUID instance for any given object during this object lifetime.

Parameters:

obj - object to return the ObjGUID for

Returns:

unique identifier associated with the obj

getTargetGUID

public static ObjGUID getTargetGUID(java.lang.Object obj)

Returns unique identifier (ObjGUID) associated with the given remote object. If the obj represents the RMIX stub, the GUID of the original object is returned.

Parameters:

obj - the object to return the ObjGUID for

Returns:

the ObjGUID associated with the obj.

export

public static ServerRef export(java.rmi.Remote target)
                        throws java.rmi.RemoteException

Exports the remote object using default export properties. Typically, it implies use of default RMIX provider and protocol, default (empty) export parameters, and no interceptor. However, if this call is performed from within a remote call at the server side, the properties of the current remote target are inherited.

Parameters:

target - remote object to export.

Returns:

newly created server reference.

Throws:

java.rmi.RemoteException - if export fails.

export

public static ServerRef export(InvocationTarget target)
                        throws java.rmi.RemoteException

Exports the remote object using default export properties. Typically, it implies use of default RMIX provider and protocol and default (empty) export parameters. However, if this call is performed from within a remote call at the server side, the properties of the current remote target are inherited. Also, if this call is performed in order to export parameter passed to a remote method, and the stub has associated exporter, it will be used to perform export.

Parameters:

target - remote target to export.

Returns:

newly created server reference.

Throws:

java.rmi.RemoteException - if export fails.

export

public static ServerRef export(java.rmi.Remote target,
                               ServerRef context)
                        throws java.rmi.RemoteException

Exports the remote object using export properties from a given context server reference.

Parameters:

target - remote target to export.

context - the server reference to use as a context.

Returns:

newly created server reference.

Throws:

java.rmi.RemoteException - if export fails.

export

public static ServerRef export(InvocationTarget target,
                               ServerRef context)
                        throws java.rmi.RemoteException

Exports the remote object using export properties from a given context server reference.

Parameters:

target - remote target to export.

context - the server reference to use as a context.

Returns:

newly created server reference.

Throws:

java.rmi.RemoteException - if export fails.

export

public static ServerRef export(java.rmi.Remote target,
                               java.lang.String protocol,
                               Parameters exportParams)
                        throws ProviderNotFoundException,
                               java.rmi.RemoteException,
                               IllegalParameterException

Exports the remote object using specified protocol and parameters. The parameters supplied by the user are not modified.

Parameters:

protocol - name of RMIX protocol to use.

target - remote object to export.

exportParams - export parameters.

Returns:

newly created server reference.

Throws:

ProviderNotFoundException - if the protocol service provider cannot be found.

java.rmi.RemoteException - if export fails.

IllegalParameterException - if the provider encounters unsupported or illegal export parameter.

export

public static ServerRef export(InvocationTarget target,
                               java.lang.String protocol,
                               Parameters exportParams)
                        throws ProviderNotFoundException,
                               java.rmi.RemoteException,
                               IllegalParameterException

Exports the remote object specified as the invocation target using specified protocol and parameters. The parameters supplied by the user are not modified.

Parameters:

protocol - name of RMIX protocol to use.

target - remote object to export.

exportParams - export parameters.

Returns:

newly created server reference.

Throws:

ProviderNotFoundException - if the protocol service provider cannot be found.

java.rmi.RemoteException - if export fails.

IllegalParameterException - if the provider encounters unsupported or illegal export parameter.

export

public static ServerRef export(java.rmi.Remote target,
                               java.lang.String protocol,
                               java.lang.String provider,
                               Parameters exportParams)
                        throws ProviderNotFoundException,
                               java.rmi.RemoteException,
                               IllegalParameterException

Exports the remote object using specified protocol, provider and parameters. The parameters supplied by the user are not modified.

Parameters:

protocol - name of RMIX protocol to use.

provider - name of RMIX provider to use.

target - remote object to export.

exportParams - export parameters.

Returns:

newly created server reference.

Throws:

ProviderNotFoundException - if the protocol service provider cannot be found.

java.rmi.RemoteException - if export fails.

IllegalParameterException - if the provider encounters unsupported or illegal export parameter.

export

public static ServerRef export(InvocationTarget target,
                               java.lang.String protocol,
                               java.lang.String provider,
                               Parameters exportParams)
                        throws ProviderNotFoundException,
                               java.rmi.RemoteException,
                               IllegalParameterException

Exports the remote object specified as the invocation target using specified RMIX protocol, provider and parameters. The parameters supplied by the user are not modified.

Parameters:

protocol - name of RMIX protocol to use.

provider - name of RMIX provider to use.

target - the target to export.

exportParams - export parameters.

Returns:

newly created server reference.

Throws:

ProviderNotFoundException - if the protocol service provider cannot be found.

java.rmi.RemoteException - if export fails.

IllegalParameterException - if the provider encounters unsupported or illegal export parameter.

bind

public static java.rmi.Remote bind(RemoteRef remoteRef)
                            throws java.lang.ClassNotFoundException,
                                   InvalidInterfaceException

Creates dynamic proxy for a given remote reference using default bind properties. Typically, this is equivalent to invoking bind(remoteRef, null, null, true) thus using default parameters, thread's context class loader and resolving all remote interfaces. However, if this call is performed by the RMIX provider handling a remote call at the client side, the properties of the original stub are used instead.

Parameters:

remoteRef - remote reference to to bind to

Returns:

newly created dynamic proxy

Throws:

java.lang.ClassNotFoundException - if some of remote interfaces cannot be resolved

InvalidInterfaceException - if some of interfaces are not valid remote interfaces

bind

public static java.rmi.Remote bind(RemoteRef remoteRef,
                                   Parameters bindParams,
                                   java.lang.ClassLoader cloader,
                                   boolean resolveAll)
                            throws java.lang.ClassNotFoundException,
                                   InvalidInterfaceException,
                                   IllegalParameterException

Creates dynamic proxy for a given remote reference using specified bind parameters and a given class loader. The parameters supplied by the user are not modified. In a standard case, a dynamic remote stub with pass-by-copy semantics is created and returned. If the remote reference is local to the server, and if the "requested binding" property is different than "REMOTE" and if it is authorized by the "allowed binding" property, the returned stub may be 1. the target object if the "DIRECT" binding is requested, or 2. the proxy with pass-by-reference semantics if "PASSBYREF" binding is requested.

Parameters:

remoteRef - remote reference to to bind to.

cloader - class loader used to define proxy and load interfaces.

resolveAll - if true, all remote interfaces must be resolved or ClassNotFoundException will be thrown.

Returns:

newly created dynamic proxy.

Throws:

java.lang.ClassNotFoundException - if resolveAll set to true and some of remote interfaces cannot be resolved by the specified class loader.

InvalidInterfaceException - if some of interfaces are not valid remote interfaces.

IllegalParameterException - if the provider encounters unsupported or illegal bind parameter.

wrap

public static java.rmi.Remote wrap(java.rmi.Remote target)
                            throws java.rmi.RemoteException,
                                   java.lang.ClassNotFoundException,
                                   InvalidInterfaceException

Creates serializable dynamic proxy for a given target object with a default protocol service provider, using current thread's context class loader and resolving all interfaces.

Parameters:

target - remote object to export.

Returns:

newly created dynamic proxy.

Throws:

java.rmi.RemoteException - if export fails.

java.lang.ClassNotFoundException - if some of target's remote interfaces cannot be resolved.

InvalidInterfaceException - if some of target's remote interfaces are not valid.

wrap

public static java.rmi.Remote wrap(java.rmi.Remote target,
                                   java.lang.String protocol)
                            throws ProviderNotFoundException,
                                   java.rmi.RemoteException,
                                   java.lang.ClassNotFoundException,
                                   InvalidInterfaceException

Creates serializable dynamic proxy for a given target object with specified protocol service provider, using current thread's context class loader and resolving all interfaces.

Parameters:

target - remote object to export.

protocol - protocol name

Returns:

newly created dynamic proxy.

Throws:

java.rmi.RemoteException - if export fails.

ProviderNotFoundException - if requested provider cannot be found

java.lang.ClassNotFoundException - if some of remote interfaces cannot be resolved.

InvalidInterfaceException - if some of interfaces are not valid remote interfaces.

wrap

public static java.rmi.Remote wrap(java.rmi.Remote target,
                                   java.lang.String protocol,
                                   java.lang.ClassLoader cloader,
                                   boolean resolveAll)
                            throws ProviderNotFoundException,
                                   java.rmi.RemoteException,
                                   java.lang.ClassNotFoundException,
                                   InvalidInterfaceException

Creates serializable dynamic proxy for a given target object with specified protocol service provider and using specified class loader.

Parameters:

target - remote object to export.

protocol - protocol name.

cloader - class loader used to define proxy and load interfaces.

resolveAll - if true, all remote interfaces must be resolved or ClassNotFoundException will be thrown.

Returns:

newly created dynamic proxy.

Throws:

ProviderNotFoundException - if requested provider cannot be found.

java.rmi.RemoteException - if export fails.

java.lang.ClassNotFoundException - if resolveAll set to true and some of remote interfaces cannot be resolved by the specified class loader.

InvalidInterfaceException - if some of interfaces are not valid remote interfaces.

defaultProvider

public static java.lang.String defaultProvider()

Gets the name of the default RMIX provider.

defaultProtocol

public static java.lang.String defaultProtocol()

Gets the name of the default RMIX protocol.

getClientContext

public static Rmix.ClientContext getClientContext()

During remote call processing on the client side, returns the current RMIX client context; otherwise, returns null. Represents the context of a thread from which the method was invoked. The only place in which this method can return non-null value when invoked from the application classes is if called by custom marshallers and client socket factories.

Returns:

the current RMIX client context, or null if none.

getServerContext

public static Rmix.ServerContext getServerContext()

During remote call dispatch on the server side, returns the current RMIX server context; otherwise, returns null. Represents the context of a thread from which the method was invoked.

Returns:

the current RMIX server context, or null if none.