agilermi.core

Class RMIRegistry

java.lang.Object

agilermi.core.RMIRegistry

public final class RMIRegistry
extends java.lang.Object

Defines a class that accepts new TCP connections over a port of the local machine and automatically creates and manages the object sockets to export remote objects. It integrates a registry of exported objects. The instances of this class can be shared among more than one RMIHandler to obtain a multi-peer interoperability. This class can be instantiated through its RMIRegistry.Builder whose instances are constructed by the builder() factory method.

Instantiation example:
RMIRegistry registry = RMIRegistry.builder().build();

Author:

Salvatore Giampa'

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RMIRegistry.Builder Builder for RMIRegistry.
static class	RMIRegistry.MethodAnnotationRegistry The method register marks remote methods to be executed according the preferred invocation policies.

Method Summary

Modifier and Type	Method and Description
void	addCodebase(java.lang.String url) Add a new static codebase that will be sent to the other machines.
void	addCodebase(java.net.URL url) Add a new static codebase that will be sent to the other machines.
void	addCodebases(java.lang.Iterable<java.net.URL> urls) Add new static codebases that will be sent to the other machines.
void	addCodebases(java.lang.String... urls) Add new static codebases that will be sent to the other machines.
void	addCodebases(java.net.URL... urls) Add new static codebases that will be sent to the other machines.
boolean	allInvocationFaultsSuppressed() Gets the suppression state of the RMI faults.
void	attachFaultHandler(RMIFaultHandler o) Attach a RMIFaultHandler object
static RMIRegistry.Builder	builder() Creates a new RMIRegistry.Builder instance, used to configure and start a new RMIRegistry instance.
void	clearCodebasesSet() Equinvalent to calling RMIClassLoader.clearCodebasesSet() on the result of the method getRmiClassLoader().
void	closeAllConnections(java.lang.String host, int port, boolean signalFault) Close all currently active connections to the specified remote socket (host/port).
void	detachFailureHandler(RMIFaultHandler o) Detach a RMIFaultHandler object
void	disableListener() Disable the registry listener.
void	enableListener(int port, boolean daemon) Enable the registry listener on the selected port.
RMIRegistry	exportInterface(java.lang.Class<?> remoteIf) Marks an interface to automatically create remote references for objects that are sent as arguments for an invocation or as return values.
RMIRegistry	exportInterfaces(java.lang.Class<?>... interfaces) Exports the specified interfaces as remote.
void	finalize() Finalizes this registry instance and all its current open connections.
void	finalize(boolean signalHandlersFailures) Finalizes this registry instance and all its current open connections.
RMIAuthenticator	getAuthenticator() Gets the rmiAuthenticator of this registry
ClassLoaderFactory	getClassLoaderFactory() Gets the class loader factory used by this registry to decode remote classes when code mobility is enabled.
java.util.Set<java.net.URL>	getCodebases() This will return all the static codebases and all the received codebases whose classes are currently instantiated.
long	getHandlerFaultMaxLife() Gets the handler maximum life used to simulate connection failures.
int	getLatencyTime() Gets the estimate of the TCP connection latency time given by the developer.
int	getLeaseTime() Gets the lease timeout after that the distributed garbage collection mechanism will remove a non-named object from the registry.
int	getListenerPort() Gets the port on which the listener was started on last time
RMIRegistry.MethodAnnotationRegistry	getMethodAnnotationRegistry() Gets the RMIRegistry.MethodAnnotationRegistry instance bound to this registry.
java.lang.Class<java.lang.Exception>	getRemoteExceptionReplace() Gets the RemoteException replacing class set by invoking the replaceRemoteException(Class) method.
java.util.List<java.lang.Class<?>>	getRemoteInterfaces(java.lang.Class<?> cls) Gets the remote interfaces implemented by the specified class and its super-classes
java.util.List<java.lang.Class<?>>	getRemoteInterfaces(java.lang.Object object) Gets the remote interfaces implemented by the class of the specified object
java.util.List<java.lang.Class<?>>	getRemoteInterfaces(java.lang.String objectId) Gets the remote interfaces implemented by the class of the remote object associated to the specified object identifier
java.lang.Object	getRemoteObject(java.lang.String objectId) Gets a published remote object by identifier
java.lang.String	getRemoteObjectId(java.lang.Object object) Gets the identifier of a remote object published on this registry
RMIClassLoader	getRmiClassLoader() Returns the RMIClassLoader instance used to load classes from remote codebase.
RMIHandler	getRMIHandler(java.lang.String host, int port) Gets an handler for the specified host.
RMIHandler	getRMIHandler(java.lang.String host, int port, boolean newConnection) Gets an handler for the specified host.
int	getSkeletonInvocationCacheSize() Gets the size of invocations cache for each skeleton.
boolean	getStateConsistencyOnFaultEnabled() Gets the enabling status of the mechanism that guarantees the status consistency between stubs and remote objects after a connection fault.
java.lang.Object	getStub(java.lang.String address, int port, java.lang.String objectId) Gets a stub for the specified object identifier representing a remote object on a remote machine.
java.lang.Object	getStub(java.lang.String address, int port, java.lang.String objectId, java.lang.Class<?>... stubInterfaces) Builds a stub for the specified object identifier on the specified host respect to the given interface.
java.lang.String	getStubHost(java.lang.Object stub) Gets the remote host of the specified RMI stub.
java.lang.String	getStubObjectIdentifier(java.lang.Object stub) Gets the object identifier of the specified RMI stub.
int	getStubPort(java.lang.Object stub) Gets the remote host port of the specified RMI stub.
StubRetriever	getStubRetriever() Gets a StubRetriever instance linked to this registry
boolean	isAutomaticReferencingEnabled() Returns the status of the automatic referencing.
boolean	isCodeDownloadingEnabled() Gets the code mobility enable flag
boolean	isMultiConnectionMode() Gets the multi-connection mode enable state.
boolean	isRemote(java.lang.Class<?> remoteIf) Check if a class is marked for automatic referencing.
java.lang.String	publish(java.lang.Object object) Publish the given object respect to the specified interface.
void	publish(java.lang.String name, java.lang.Object object) Publish the given object respect to the specified interface.
void	removeAuthentication(java.lang.String host, int port) Removes authentication details for a remote host
void	removeCodebase(java.net.URL url) Removes a static codebase previously added.
void	replaceRemoteException(java.lang.Class<java.lang.Exception> exceptionClass) Let the stubs to throw the specified exception alternatively to RemoteException on communication errors.
void	setAuthentication(java.lang.String host, int port, java.lang.String authId, java.lang.String authPassphrase) Adds authentication details for a remote host
void	setCodeDownloadingEnabled(boolean codeMobilityEnabled)
void	setLatencyTime(int latencyTime) Sets an estimate of the TCP connection latency time.
void	setMultiConnectionMode(boolean multiConnectionMode) Enables or disables multi-connection mode.
void	unexportInterface(java.lang.Class<?> remoteIf) Remove a automatic referencing mark for the interface.
void	unpublish(java.lang.Object object) Unpublish an object respect to the given interface

Methods inherited from class java.lang.Object

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

Method Detail

builder

public static RMIRegistry.Builder builder()

Creates a new RMIRegistry.Builder instance, used to configure and start a new RMIRegistry instance.

Returns:

a new RMIRegistry.Builder instance

replaceRemoteException

public void replaceRemoteException(java.lang.Class<java.lang.Exception> exceptionClass)

Let the stubs to throw the specified exception alternatively to RemoteException on communication errors.

Parameters:

exceptionClass - the alternative exception class or null if the RemoteException must not be replaced.

getRemoteExceptionReplace

public java.lang.Class<java.lang.Exception> getRemoteExceptionReplace()

Gets the RemoteException replacing class set by invoking the replaceRemoteException(Class) method.

Returns:

the exception class that is currently replacing RemoteException or null if RemoteException is not currently replaced.

allInvocationFaultsSuppressed

public boolean allInvocationFaultsSuppressed()

Gets the suppression state of the RMI faults.

Returns:

true if and only if all invocation faults are suppressed

See Also:

RMIRegistry.Builder.suppressAllInvocationFaults(boolean)

setMultiConnectionMode

public void setMultiConnectionMode(boolean multiConnectionMode)

Enables or disables multi-connection mode.

Parameters:

multiConnectionMode - true to enable, false to disable

See Also:

RMIRegistry.Builder.setMultiConnectionMode(boolean)

isMultiConnectionMode

public boolean isMultiConnectionMode()

Gets the multi-connection mode enable state.

Returns:

true if multi-connection mode is enabled, false otherwise

See Also:

setMultiConnectionMode(boolean)

getSkeletonInvocationCacheSize

public int getSkeletonInvocationCacheSize()

Gets the size of invocations cache for each skeleton.
See RMIRegistry.Builder.setSkeletonInvocationCacheSize(int) for more details.

Returns:

the max number of invocation results that each skeleton stores in its cache

getStateConsistencyOnFaultEnabled

public boolean getStateConsistencyOnFaultEnabled()

Gets the enabling status of the mechanism that guarantees the status consistency between stubs and remote objects after a connection fault. See RMIRegistry.Builder.setStateConsistencyOnFaultEnabled(boolean) for more details.

Returns:

true if state consistency is guaranteed, false otherwise

getHandlerFaultMaxLife

public long getHandlerFaultMaxLife()

Gets the handler maximum life used to simulate connection failures. See RMIRegistry.Builder.setHandlerFaultMaxLife(long) for more details.

Returns:

the maximum handler life before a connection failure is simulated, in milliseconds.

isAutomaticReferencingEnabled

public boolean isAutomaticReferencingEnabled()

Returns the status of the automatic referencing.

See RMIRegistry.Builder.setAutomaticReferencingEnabled(boolean) for more information.

Returns:

true if automatic referencing is enabled, false otherwise

getClassLoaderFactory

public ClassLoaderFactory getClassLoaderFactory()

Gets the class loader factory used by this registry to decode remote classes when code mobility is enabled.

Returns:

the ClassLoaderFactory used by this registry

getLeaseTime

public int getLeaseTime()

Gets the lease timeout after that the distributed garbage collection mechanism will remove a non-named object from the registry.

Returns:

the lease timeout value in milliseconds

getLatencyTime

public int getLatencyTime()

Gets the estimate of the TCP connection latency time given by the developer. This constant is used to determine update times across the RMI network (e.g. when a remote object has zero pointers its removal from registry is scheduled to be executed after the latency time passed).

Returns:

the latency time in milliseconds

See Also:

RMIRegistry.Builder.setLatencyTime(int)

setLatencyTime

public void setLatencyTime(int latencyTime)

Sets an estimate of the TCP connection latency time. This constant is used to determine update times across the RMI network (e.g. when a remote object has zero pointers its removal from registry is scheduled to be executed after the latency time passed).

Parameters:

latencyTime - a time in milliseconds

See Also:

RMIRegistry.Builder.setLatencyTime(int)

setCodeDownloadingEnabled

public void setCodeDownloadingEnabled(boolean codeMobilityEnabled)

isCodeDownloadingEnabled

public boolean isCodeDownloadingEnabled()

Gets the code mobility enable flag

Returns:

true if this registry accepts code from remote codebases, false otherwise

clearCodebasesSet

public void clearCodebasesSet()

Equinvalent to calling RMIClassLoader.clearCodebasesSet() on the result of the method getRmiClassLoader().

getCodebases

public java.util.Set<java.net.URL> getCodebases()

This will return all the static codebases and all the received codebases whose classes are currently instantiated.

Returns:

all actually used codebases

addCodebases

public void addCodebases(java.lang.Iterable<java.net.URL> urls)

Add new static codebases that will be sent to the other machines.

Parameters:

urls - the codebases to add

See Also:

addCodebase(URL)

addCodebases

public void addCodebases(java.net.URL... urls)

Add new static codebases that will be sent to the other machines.

Parameters:

urls - the codebases to add

See Also:

addCodebase(URL)

addCodebase

public void addCodebase(java.net.URL url)

Add a new static codebase that will be sent to the other machines.

A static codebase is constantly active and it is supposed its classes are always used and available in the current RMI node. It is always propagated to other RMI nodes to be ready to load it if a class from it is sent over the stream.

Parameters:

url - the codebase to add

addCodebases

public void addCodebases(java.lang.String... urls)
                  throws java.net.MalformedURLException

Add new static codebases that will be sent to the other machines.

Parameters:

urls - the codebases to add

Throws:

java.net.MalformedURLException - if any of the specified URLs is malformed

See Also:

addCodebase(URL)

addCodebase

public void addCodebase(java.lang.String url)
                 throws java.net.MalformedURLException

Add a new static codebase that will be sent to the other machines.

A static codebase is constantly active and it is supposed its classes are always used and available in the current RMI node. It is always propagated to other RMI nodes to be ready to load it if a class from it is sent over the stream.

Parameters:

url - the codebase to add

Throws:

java.net.MalformedURLException - if the specified URL is malformed

removeCodebase

public void removeCodebase(java.net.URL url)

Removes a static codebase previously added.

Parameters:

url - the URL of the codebase

See Also:

addCodebase(URL)

getRmiClassLoader

public RMIClassLoader getRmiClassLoader()

Returns the RMIClassLoader instance used to load classes from remote codebase. This instance can be used to load specific classes that are not in the current classpath.

Returns:

the RMIClassLoader instance used by this registry

setAuthentication

public void setAuthentication(java.lang.String host,
                              int port,
                              java.lang.String authId,
                              java.lang.String authPassphrase)

Adds authentication details for a remote host

Parameters:

host - the remote host

port - the remote port

authId - the authentication identifier

authPassphrase - the authentication pass-phrase

removeAuthentication

public void removeAuthentication(java.lang.String host,
                                 int port)

Removes authentication details for a remote host

Parameters:

host - the remote host

port - the remote port

finalize

public void finalize()

Finalizes this registry instance and all its current open connections.

Overrides:

finalize in class java.lang.Object

finalize

public void finalize(boolean signalHandlersFailures)

Finalizes this registry instance and all its current open connections.

Parameters:

signalHandlersFailures - set to true if all the RMIHandler instances created by this registry should send a signal to the attached fault handlers

getStubRetriever

public StubRetriever getStubRetriever()

Gets a StubRetriever instance linked to this registry

Returns:

a StubRetriever object

getStub

public java.lang.Object getStub(java.lang.String address,
                                int port,
                                java.lang.String objectId,
                                java.lang.Class<?>... stubInterfaces)

Builds a stub for the specified object identifier on the specified host respect to the given interface. This method creates the stub locally without performing TCP communications. Therefore, this method allows to get a stub when the remote machine is actually not connected, too, and it is preferable to the getStub(String, int, String) method in most real and complex applications.

To know about the possible unchecked exceptions thrown by this method see documentation of newProxyInstance method.

Parameters:

address - the host address

port - the host port

objectId - the remote object identifier

stubInterfaces - the interfaces implemented by the stub

Returns:

the stub object

See Also:

getStub(String, int, String)

getStub

public java.lang.Object getStub(java.lang.String address,
                                int port,
                                java.lang.String objectId)
                         throws java.net.UnknownHostException,
                                java.io.IOException,
                                java.lang.InterruptedException

Gets a stub for the specified object identifier representing a remote object on a remote machine. This method performs a request to the remote machine to get the remote interfaces of the remote object, then it creates the stub. All the remote interfaces of the remote object must be visible by the default class loader and they must be known by each local runtime.

To know about the possible unchecked exceptions thrown by this method see documentation of newProxyInstance method.

Parameters:

address - the host address

port - the host port

objectId - the object identifier

Returns:

A dynamic proxy object that represents the remote instance. It is an instance for the specified stub interface

Throws:

java.net.UnknownHostException - if the remote host cannot be found

java.io.IOException - if an I/O error occurs while contacting the remote machine

java.lang.InterruptedException - if the current thread is interrupted during operation

See Also:

getStub(String, int, String, Class...)

getRMIHandler

public RMIHandler getRMIHandler(java.lang.String host,
                                int port)
                         throws java.io.IOException

Gets an handler for the specified host. If it has not been created, then creates it. If any handler already exists and multi-connection mode is disabled, gets one of them. If multi-connection mode is enabled, this method creates a new, never used, handler.

Parameters:

host - the host address

port - the host port

Returns:

a handler related to the specified host

Throws:

java.net.UnknownHostException - if the host address cannot be resolved

java.io.IOException - if I/O errors occur

See Also:

getRMIHandler(String, int, boolean)

getRMIHandler

public RMIHandler getRMIHandler(java.lang.String host,
                                int port,
                                boolean newConnection)
                         throws java.io.IOException

Gets an handler for the specified host. If it has not been created, then creates it. If a new connection must be created, this method returns a new, never used, handler.

Parameters:

host - the host address

port - the host port

newConnection - set to true to create a new handler without getting an already existing one

Returns:

a handler related to the specified host

Throws:

java.net.UnknownHostException - if the host address cannot be resolved

java.io.IOException - if I/O errors occurs

See Also:

getRMIHandler(String, int)

closeAllConnections

public void closeAllConnections(java.lang.String host,
                                int port,
                                boolean signalFault)

Close all currently active connections to the specified remote socket (host/port).
The stubs referring to the objects on the specified socket can create new connections if they are used.

Parameters:

host - the string address of the remote host

port - the port of the remote socket

signalFault - set to true if each handler connected to the remote host should send a signal to the fault handlers instances attached to this registry

enableListener

public void enableListener(int port,
                           boolean daemon)
                    throws java.io.IOException

Enable the registry listener on the selected port. This method enables the registry to accept new external incoming connections for RMI

Parameters:

port - the port to start the listener on

daemon - if true, the listener is started as daemon, that is it will be stopped when all other non-daemon threads in the application will be terminated.

Throws:

java.io.IOException - if I/O errors occur

disableListener

public void disableListener()

Disable the registry listener. This method will disallow the registry to accept new incoming connections, but does not close the current open ones.

getListenerPort

public int getListenerPort()

Gets the port on which the listener was started on last time

Returns:

The last listener TCP port

getAuthenticator

public RMIAuthenticator getAuthenticator()

Gets the rmiAuthenticator of this registry

Returns:

the rmiAuthenticator associated to this registry

publish

public void publish(java.lang.String name,
                    java.lang.Object object)

Publish the given object respect to the specified interface.

Parameters:

name - the identifier to use for this service

object - the implementation of the service to publish

Throws:

java.lang.IllegalArgumentException - if the specified identifier was already bound or if the objectId parameter matches the automatic referencing objectId pattern that is /\#[0-9]+/

publish

public java.lang.String publish(java.lang.Object object)

Publish the given object respect to the specified interface. The identifier is automatically generated and returnedCondition

Parameters:

object - the implementation of the service to publish

Returns:

the generated identifier

unpublish

public void unpublish(java.lang.Object object)

Unpublish an object respect to the given interface

Parameters:

object - the object to unpublish

attachFaultHandler

public void attachFaultHandler(RMIFaultHandler o)

Attach a RMIFaultHandler object

Parameters:

o - the fault handler

detachFailureHandler

public void detachFailureHandler(RMIFaultHandler o)

Detach a RMIFaultHandler object

Parameters:

o - the fault handler

getRemoteObject

public java.lang.Object getRemoteObject(java.lang.String objectId)

Gets a published remote object by identifier

Parameters:

objectId - object identifier

Returns:

the remotized object

getRemoteObjectId

public java.lang.String getRemoteObjectId(java.lang.Object object)

Gets the identifier of a remote object published on this registry

Parameters:

object - the published object reference

Returns:

the associated identifier or null if no entry was found

exportInterfaces

public RMIRegistry exportInterfaces(java.lang.Class<?>... interfaces)

Exports the specified interfaces as remote. This method calls the exportInterface(Class) method for each specified interface.

Parameters:

interfaces - the interfaces to export

Returns:

this registry

See Also:

exportInterface(Class)

exportInterface

public RMIRegistry exportInterface(java.lang.Class<?> remoteIf)

Marks an interface to automatically create remote references for objects that are sent as arguments for an invocation or as return values. The objects are automatically published on this registry when the related parameter of the stub method has a type that matches with the marked interface

Parameters:

remoteIf - the interface to mark

Returns:

this registry

unexportInterface

public void unexportInterface(java.lang.Class<?> remoteIf)

Remove a automatic referencing mark for the interface. See the exportInterface(Class) method. All the objects automatically referenced until this call, remains published in the registry.

Parameters:

remoteIf - the interface to unmark

isRemote

public boolean isRemote(java.lang.Class<?> remoteIf)

Check if a class is marked for automatic referencing. A concrete or abstract class is never remote. An interface is remote if it, directly or indirectly, extends the Remote interface or if it was exported or if it extends, directly or indirectly, an interface that was exported on this registry to be remote.
See the exportInterface(Class) method.

Parameters:

remoteIf - the interface to check

Returns:

true if the interface is marked for automatic referencing, false otherwise

getRemoteInterfaces

public java.util.List<java.lang.Class<?>> getRemoteInterfaces(java.lang.String objectId)

Gets the remote interfaces implemented by the class of the remote object associated to the specified object identifier

Parameters:

objectId - the object identifier

Returns:

the remote interfaces of the remote object

getRemoteInterfaces

public java.util.List<java.lang.Class<?>> getRemoteInterfaces(java.lang.Object object)

Gets the remote interfaces implemented by the class of the specified object

Parameters:

object - the object

Returns:

the remote interfaces of the object

getRemoteInterfaces

public java.util.List<java.lang.Class<?>> getRemoteInterfaces(java.lang.Class<?> cls)

Gets the remote interfaces implemented by the specified class and its super-classes

Parameters:

cls - the class

Returns:

the remote interfaces implemented by the class

getStubHost

public java.lang.String getStubHost(java.lang.Object stub)

Gets the remote host of the specified RMI stub.

Parameters:

stub - the RMI stub

Returns:

the host address or name

Throws:

java.lang.IllegalArgumentException - if the specified object is not an RMI stub

getStubPort

public int getStubPort(java.lang.Object stub)

Gets the remote host port of the specified RMI stub.

Parameters:

stub - the RMI stub

Returns:

the host port

Throws:

java.lang.IllegalArgumentException - if the specified object is not an RMI stub

getStubObjectIdentifier

public java.lang.String getStubObjectIdentifier(java.lang.Object stub)

Gets the object identifier of the specified RMI stub.

Parameters:

stub - the RMI stub

Returns:

the identifier of the remote object

Throws:

java.lang.IllegalArgumentException - if the specified object is not an RMI stub

getMethodAnnotationRegistry

public RMIRegistry.MethodAnnotationRegistry getMethodAnnotationRegistry()

Gets the RMIRegistry.MethodAnnotationRegistry instance bound to this registry.

Returns:

a RMIRegistry.MethodAnnotationRegistry instance