agilermi.core

Class RMIRegistry.Builder

java.lang.Object

agilermi.core.RMIRegistry.Builder

Enclosing class:

RMIRegistry

public static class RMIRegistry.Builder
extends java.lang.Object

Builder for RMIRegistry. A new instance of this class can be returned by the RMIRegistry.builder() static method. A new instance of this class wraps all the defaults for RMIRegistry and allows to modify them. When the configuration has been terminated, a new RMIRegistry instance can be obtained by the build() method.

An instance of this class can be re-used after each call to the build() method to generate new instances of RMIRegistry. Each call to the build() method does not reset the builder instance to its default state.

Author:

Salvatore Giampa'

Method Summary

Modifier and Type	Method and Description
RMIRegistry.Builder	addCodebase(java.lang.String url) Utility method to add a codebase at building time.
RMIRegistry.Builder	addCodebase(java.net.URL url) Utility method to add a codebase at building time.
RMIRegistry.Builder	addCodebases(java.lang.Iterable<java.net.URL> urls) Utility method to add code-bases at building time.
RMIRegistry.Builder	addCodebases(java.lang.String... urls) Utility method to add code-bases at building time.
RMIRegistry.Builder	addCodebases(java.net.URL... urls) Utility method to add code-bases at building time.
RMIRegistry	build() Builds the RMIRegistry instance.
RMIRegistry.Builder	clearCodebasesSet() Remove all the codebases added to this builder.
RMIRegistry.Builder	replaceRemoteException(java.lang.Class<java.lang.Exception> exceptionClass) Let the stubs to throw the specified exception alternatively to RemoteException on communication errors.
RMIRegistry.Builder	setAuthenticator(RMIAuthenticator rmiAuthenticator) Set an RMIAuthenticator object that intercept authentication and authorization requests from remote machines.
RMIRegistry.Builder	setAutomaticReferencingEnabled(boolean automaticReferencingEnabled) Enables or disables the automatic referencing which is the mechanism that replace all the remote objects with its stubs when they are transmitted over RMI streams.
RMIRegistry.Builder	setClassLoaderFactory(ClassLoaderFactory classLoaderFactory) Sets the class loader factory used by this registry to decode remote classes when code mobility is enabled.
RMIRegistry.Builder	setCodeDownloadingEnabled(boolean codeDownloadingEnabled) Enable dynamic code downloading.
RMIRegistry.Builder	setHandlerFaultMaxLife(long handlerFaultMaxLife) Sets the maximum life of each handler.
RMIRegistry.Builder	setLatencyTime(int latencyTime) Sets an estimate of the TCP connection latency time.
RMIRegistry.Builder	setLeaseTime(int leaseTime) Sets the lease timeout after that the distributed garbage collection mechanism will remove a non-named object from the registry.
RMIRegistry.Builder	setMultiConnectionMode(boolean multiConnectionMode) Enables or disables multi-connection mode.
RMIRegistry.Builder	setProtocolEndpointFactory(ProtocolEndpointFactory protocolEndpointFactory) Sets the ProtocolEndpointFactory instance to use in the registry to build.
RMIRegistry.Builder	setSkeletonInvocationCacheSize(int skeletonInvocationCacheSize) Sets the cache size of invocations results for each skeleton.
RMIRegistry.Builder	setSocketFactories(javax.net.SocketFactory socketFactory, javax.net.ServerSocketFactory serverSocketFactory) Sets the socket factories that the registry will use.
RMIRegistry.Builder	setStateConsistencyOnFaultEnabled(boolean stateConsistencyOnFaultEnabled) When enabled, this flag ensures that, after a connection fault, a stub will be reconnected with the same remote object instance that existed before the fault.
RMIRegistry.Builder	suppressAllInvocationFaults(boolean suppressAllInvocationFaults) Enables or disables the suppression of all remote invocation faults.

Methods inherited from class java.lang.Object

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

Method Detail

replaceRemoteException

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

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

Default: null (RemoteException is not replaced)

Parameters:

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

Returns:

this builder

suppressAllInvocationFaults

public RMIRegistry.Builder suppressAllInvocationFaults(boolean suppressAllInvocationFaults)

Enables or disables the suppression of all remote invocation faults. If this flag is enabled all the stubs that are connected to the registry want not throw remote exceptions, so the remote methods can be declared without throwing these exceptions. This is useful when turning an existing code into a distributed one.

When all faults are suppressed, each remote method that is called from remote which encounter an RMI fault, will return the default value for its return type. The default values are 0 for all numerical primitive (such as int) and non-primitive (such as Integer) types, false for the boolean type and null for object types.

Default: false

Parameters:

suppressAllInvocationFaults - true to suppress all invocation faults on the stubs

Returns:

this builder

setMultiConnectionMode

public RMIRegistry.Builder setMultiConnectionMode(boolean multiConnectionMode)

Enables or disables multi-connection mode. If this mode is enabled, the registry tends to create a new connection for each created or received stub.

When disabled the registry tends to share the same TCP connections across all local stubs.

Default: false (multi-connection mode is disabled)

Parameters:

multiConnectionMode - true to enable, false to disable

Returns:

this builder

setStateConsistencyOnFaultEnabled

public RMIRegistry.Builder setStateConsistencyOnFaultEnabled(boolean stateConsistencyOnFaultEnabled)

When enabled, this flag ensures that, after a connection fault, a stub will be reconnected with the same remote object instance that existed before the fault. If this is not possible, for instance, due to a crash of the remote JVM process, the stub will be no longer reusable.

If this is disabled and a new instance of the remote object is re-published, the stub will be reconnected, but, given the state reached by the remote object before the connection fault, there is no guarantee about that it will be the same state after the connection repair.

Default: false (state consistency is not guaranteed)

Parameters:

stateConsistencyOnFaultEnabled - true to enable state consistency guarantee on connection fault

Returns:

this builder

setSkeletonInvocationCacheSize

public RMIRegistry.Builder setSkeletonInvocationCacheSize(int skeletonInvocationCacheSize)

Sets the cache size of invocations results for each skeleton. The invocation cache is used to prevent duplicate invocation requests due to connection errors.

Default: 50 entries

Parameters:

skeletonInvocationCacheSize - the max number of invocations return values to store in the cache of the skeleton

Returns:

this builder

setAutomaticReferencingEnabled

public RMIRegistry.Builder setAutomaticReferencingEnabled(boolean automaticReferencingEnabled)

Enables or disables the automatic referencing which is the mechanism that replace all the remote objects with its stubs when they are transmitted over RMI streams.

When automatic referencing is active and a remote object that was not published on the registry is transmitted as a parameter for a remote invocation or as a return value, it is automatically published on the registry. Enabling this mechanism starts a Distributed Garbage Collection service on the current node, used to remove objects that are not utilized for a time as long as the lease time.

When the automatic referencing is not active, the framework can be used as a plain old RPC middle-ware, where the Distributed Garbage Collection service is off and no object can be remote without explicitly publishing it on the RMI registry, so that this is a "service oriented" mode.

Default: true (automatic referencing is enabled)

Parameters:

automaticReferencingEnabled - set to true to enable automatic referencig, false otherwise.

Returns:

this builder

setLeaseTime

public RMIRegistry.Builder setLeaseTime(int leaseTime)

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

Default: 600000 milliseconds (10 minutes).

Parameters:

leaseTime - the lease timeout value in milliseconds

Returns:

this builder

setLatencyTime

public RMIRegistry.Builder 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).

Default: 10000 milliseconds (10 seconds).

Parameters:

latencyTime - a time in milliseconds

Returns:

this builder

setAuthenticator

public RMIRegistry.Builder setAuthenticator(RMIAuthenticator rmiAuthenticator)

Set an RMIAuthenticator object that intercept authentication and authorization requests from remote machines. Default: null (no RMIAuthenticator)

Parameters:

rmiAuthenticator - the RMIAuthenticator instance to use

Returns:

this builder

setSocketFactories

public RMIRegistry.Builder setSocketFactories(javax.net.SocketFactory socketFactory,
                                              javax.net.ServerSocketFactory serverSocketFactory)

Sets the socket factories that the registry will use.

Default: default socket factories provided by the JDK

Parameters:

socketFactory - the SocketFactory instance to use to build client sockets

serverSocketFactory - the ServerSocketFactory instance to use to build the listener server socket

Returns:

this builder

setProtocolEndpointFactory

public RMIRegistry.Builder setProtocolEndpointFactory(ProtocolEndpointFactory protocolEndpointFactory)

Sets the ProtocolEndpointFactory instance to use in the registry to build.

Default: null (no protocol customization)

Parameters:

protocolEndpointFactory - the ProtocolEndpointFactory instance that gives the ProtocolEndpoint instance in which the underlying communication streams will be wrapped in

Returns:

this builder

setCodeDownloadingEnabled

public RMIRegistry.Builder setCodeDownloadingEnabled(boolean codeDownloadingEnabled)

Enable dynamic code downloading. If code downloading is enabled, this registry will accept and download code from remote code-bases.

Default: false (the registry does not download remote code)

Parameters:

codeDownloadingEnabled - true if the dynamic code downloading must be enabled, false otherwise

Returns:

this builder

setClassLoaderFactory

public RMIRegistry.Builder setClassLoaderFactory(ClassLoaderFactory classLoaderFactory)

Sets the class loader factory used by this registry to decode remote classes when code mobility is enabled. It is necessary on some platforms that uses a different implementation of the Java Virtual Machine.

Default: null (uses an instance of URLClassLoaderFactory)

Parameters:

classLoaderFactory - the factory to use

Returns:

this builder

addCodebases

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

Utility method to add code-bases at building time. Code-bases can be added and removed after the registry construction, too.

Parameters:

urls - the URLs of the code-bases

Returns:

this builder

See Also:

addCodebase(URL)

addCodebase

public RMIRegistry.Builder addCodebase(java.net.URL url)

Utility method to add a codebase at building time. Codebases can be added and removed after the registry construction, too.

Parameters:

url - the url to the codebase

Returns:

this builder

See Also:

addCodebase(URL)

addCodebases

public RMIRegistry.Builder addCodebases(java.net.URL... urls)

Utility method to add code-bases at building time. Code-bases can be added and removed after the registry construction, too.

Parameters:

urls - the URLs of the code-bases

Returns:

this builder

See Also:

addCodebase(URL)

addCodebase

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

Utility method to add a codebase at building time. Codebases can be added and removed after the registry construction, too.

Parameters:

url - the URL to the codebase

Returns:

this builder

Throws:

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

See Also:

addCodebase(URL)

addCodebases

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

Utility method to add code-bases at building time. Code-bases can be added and removed after the registry construction, too.

Parameters:

urls - the URLs of the code-bases

Returns:

this builder

Throws:

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

See Also:

addCodebase(URL)

clearCodebasesSet

public RMIRegistry.Builder clearCodebasesSet()

Remove all the codebases added to this builder.

Returns:

this builder

See Also:

addCodebase(URL)

setHandlerFaultMaxLife

public RMIRegistry.Builder setHandlerFaultMaxLife(long handlerFaultMaxLife)

Sets the maximum life of each handler. The actual life is picked up by using an exponential distribution with a decay chosen basing on this maximum life parameter.

Setting this parameter to a value larger than 0, enables the connection failure simulation, that can be used to generically test the connection fault tolerance of the application.

Default: 0 (fault simulation is not active)

Parameters:

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

Returns:

this builder

build

public RMIRegistry build()

Builds the RMIRegistry instance. After this call, the builder will not reset and it will be reusable to build new RMIRegistry instances.

Returns:

the built RMIRegistry instance