jgroup.registry
Interface DependableRegistry

All Superinterfaces:
ExternalGMIListener, Listener, java.rmi.Remote

public interface DependableRegistry
extends ExternalGMIListener

For obtaining references to remote objects, RMI includes a registry service, that provides methods for storing and retrieving remote object references. Each registry object acts independently and maintains a different set of bindings (name, remote object), thus constituting a single point of failure. Furthermore, a registry object running on a certain host can be used to register only remote objects running on the same host; thus, in order to obtain a stub for a remote object, a client need to be aware of its location.

The registry implementation included with Jgroup has several advantages over the standard Java RMI registry. First, it enables a set of replicated remote objects to register themselves under the same name. This set forms a remote object group that can be retrieved as a single entity. All the Jgroup registry objects running in a distributed system cooperate in order to maintain a replicated database of bindings and offer a reliable and high-available repository facility. Clients no longer need to be aware of the location of a service: they can simply access the group of registry replicas and obtain a stub for every service registered in the distributed system. A stub for the registry group is obtained through the RegistryFactory.getDependableRegistry methods.

A distributed system can be designed by including a certain number of registry replicas running on different hosts and possibly on distinct portions of the communication network. Client access these replicas through standard RMI interactions as if they were a single registry, and are guaranteed that their invocation will successfully terminate, provided that at least one operational replica is running in their partition.

During a partitioning, the Jgroup registry presents a partitioned behavior reflecting the current failure scenario. The registration of a remote object inside a partition will not affect the registry replicas not contained in that partition, while a retrieval operation will not success if the service we are looking for has been registered in another partition. Nevertheless, the replicas contained in a partition consistently maintain the same set of bindings and act as a single entity; moreover, the disappearance of the partitioning causes the execution of a reconciliation protocol in order to re-establish a consistent set of bindings among the replicas that belonged to different partitions. It is important to note that this behavior is perfectly reasonable for a partitionable distributed system, since clients asking for remote services are interested only in servers running in their current partitions.

The DependableRegistry interface describes the methods of a dependable registry that can be remotely invoked. To create a registry that runs in an application, use one of the RegistryFactory.createDependableRegistry methods. To obtain a reference to a remote object registry, use one of the RegistryFactory.getDependableRegistry methods.

Since:
Jgroup 0.3
Author:
Alberto Montresor

Field Summary
static java.lang.String DEPENDABLE_REGISTRY_NAME
          Service name used to register each dependable registry replica in the local registry.
static int DREGISTRY_BOOTSTRAP_PORT
          Port number used by the dependable registry for bootstrap purpose; each dependable registry server is locally registered in a standard registry service running in the same host and using this port.
static int DREGISTRY_JGROUP_PORT
          Port number used by the dependable registry for internal communications among servers composing the dependable registry service.
 
Method Summary
 IID bind(java.lang.String name, java.rmi.Remote gmiService, java.lang.Class serverType)
          Add a replicated member object to the remote object group associated with the specified name in the registry.
 java.lang.String[] list()
          Returns an array containing the remote object group names registered in the registry.
 java.rmi.Remote lookup(java.lang.String name)
          Returns a proxy for the remote object group associated with the specified name in the registry.
 void unbind(IID bid)
          Remove a replicated remote object identified by the IID object obtained when the replica has been registered.
 

Field Detail

DREGISTRY_BOOTSTRAP_PORT

public static final int DREGISTRY_BOOTSTRAP_PORT
Port number used by the dependable registry for bootstrap purpose; each dependable registry server is locally registered in a standard registry service running in the same host and using this port.

DREGISTRY_JGROUP_PORT

public static final int DREGISTRY_JGROUP_PORT
Port number used by the dependable registry for internal communications among servers composing the dependable registry service.

DEPENDABLE_REGISTRY_NAME

public static final java.lang.String DEPENDABLE_REGISTRY_NAME
Service name used to register each dependable registry replica in the local registry.
Method Detail

lookup

public java.rmi.Remote lookup(java.lang.String name)
                       throws java.rmi.RemoteException,
                              java.rmi.NotBoundException,
                              java.rmi.AccessException
Returns a proxy for the remote object group associated with the specified name in the registry.
Parameters:
name - the name associated with the remote object group
Returns:
a proxy for the remote object group
Throws:
java.rmi.RemoteException - If remote operation failed.
java.rmi.NotBoundException - if there is no object group with this name in the registry.
java.rmi.AccessException - If this operation is not permitted.

bind

public IID bind(java.lang.String name,
                java.rmi.Remote gmiService,
                java.lang.Class serverType)
         throws java.rmi.RemoteException,
                McastRemoteException,
                java.rmi.AccessException
Add a replicated member object to the remote object group associated with the specified name in the registry.
Parameters:
name - the name associated with the remote object group
gmiService - the external GMI service associated with the member object implementation
serverType - the class object of the member object implementation
Returns:
a IID identifier used to (possibly) remove this replicated remote object from the group
Throws:
java.rmi.RemoteException - Raised when remote operation failed.
McastRemoteException - Marker used to identify methods to be invoked through multicast semantics.
java.rmi.AccessException - Raised when this operation is not permitted.

unbind

public void unbind(IID bid)
            throws java.rmi.RemoteException,
                   McastRemoteException,
                   java.rmi.NotBoundException,
                   java.rmi.AccessException
Remove a replicated remote object identified by the IID object obtained when the replica has been registered.
Parameters:
bid - the binding identifier obtained when the replica has been registered
Throws:
java.rmi.RemoteException - If remote operation failed.
McastRemoteException - Marker used to identify methods to be invoked through multicast semantics
java.rmi.NotBoundException - if there is no object with this name in the registry.
java.rmi.AccessException - If this operation is not permitted.

list

public java.lang.String[] list()
                        throws java.rmi.RemoteException,
                               java.rmi.AccessException
Returns an array containing the remote object group names registered in the registry.
Throws:
java.rmi.RemoteException - If remote operation failed.
java.rmi.AccessException - If this operation is not permitted.