Package com.tangosol.net

Interface Cluster

  • All Superinterfaces:
    ClassLoaderAware, Controllable
    public interface Cluster
extends Controllable
    The Cluster interface represents a collection of services that operate in a clustered network environment.
    Since:
    Coherence 1.1
    Author:
    gg 2002.02.08

    • Method Detail

      • getServiceNames

        Enumeration<String> getServiceNames()
        Returns an Enumeration of String objects, one for each service that has been previously registered in the cluster.

        For each name, a call to getServiceInfo(String) will return a ServiceInfo describing a service. However, the call to getService(String) may return null if that service is not available locally.

        Returns:
        Enumeration of service names
        Throws:
        IllegalStateException - thrown if the cluster service is not running or has stopped

      • getServiceInfo

        ServiceInfo getServiceInfo​(String sName)
        Returns a ServiceInfo object for the specified service name.
        Parameters:
        sName - the service name, within the cluster, that uniquely identifies a registered service
        Returns:
        a ServiceInfo for the specified service; null if that service name has not been registered
        Throws:
        IllegalStateException - thrown if the cluster service is not running or has stopped
        See Also:
        getService(String)

      • getService

        Service getService​(String sName)
        Returns a Service object for the specified service name.
        Parameters:
        sName - the service name, within the cluster, that uniquely identifies a service
        Returns:
        a Service for the specified name; null if the specified service is not available locally
        Throws:
        IllegalStateException - thrown if the cluster service is not running or has stopped
        See Also:
        getServiceInfo(String), ensureService(String, String)

      • ensureService

        Service ensureService​(String sName,
                      String sType)
        Obtains a Service object for the specified service name and type.

        If the service with the specified name already exists, a reference to the same service will be returned. Otherwise a new service object will be instantiated and returned. The service's context ClassLoader will be initialized with the Cluster's context ClassLoader.

        It is essential to understand that until the service is started using Controllable.start(), the cluster doesn't keep a reference to that service instance. Therefore, the external synchronization on the cluster object is necessary to prevent creation of a duplicate service.

        Parameters:
        sName - the service name, within the cluster, that uniquely identifies a service
        sType - the service type, that serves as a key to the cluster configuration info, allowing the cluster instantiate the corresponding service implementations if the specified service is not available locally
        Returns:
        a Service object for the specified service name an type
        Throws:
        IllegalStateException - thrown if the cluster service is not running or has stopped
        IllegalArgumentException - thrown if the type is illegal or unknown

      • suspendService

        void suspendService​(String sName)
        Suspend all members of the service identified by the specified name. A suspended Service has been placed in a "quiesced" or "deactivated" state in preparation to be shutdown. Once suspended, a service may be "resumed" or "reactivated" with the resumeService method.

        If "Cluster" is passed for the service name, all services (including the ClusterService) will be suspended.

        Parameters:
        sName - the service name
        Throws:
        IllegalStateException - thrown if the cluster service is not running or has stopped
        IllegalArgumentException - thrown if the name is illegal or unknown

      • resumeService

        void resumeService​(String sName)
        Resume all suspended members of the service identified by the specified name.

        If "Cluster" is passed for the service name, all services (including the ClusterService) will be resumed.

        Parameters:
        sName - the service name
        Throws:
        IllegalStateException - thrown if the cluster service is not running or has stopped
        IllegalArgumentException - thrown if the name is illegal or unknown

      • getMemberSet

        Set<Member> getMemberSet()
        Returns a Set of Member objects, one for each Member of the cluster.
        Returns:
        Set of cluster members
        Throws:
        IllegalStateException - thrown if the cluster service is not running or has stopped

      • getLocalMember

        Member getLocalMember()
        Returns a Member object representing the local (i.e. this JVM) member of the cluster.
        Returns:
        the local cluster member
        Throws:
        IllegalStateException - thrown if the cluster service is not running or has stopped

      • getTimeMillis

        long getTimeMillis()
        Returns the current "cluster time", which is analogous to the System.currentTimeMillis() except that the cluster time is the roughly the same for all Members in the cluster.
        Returns:
        the cluster time in milliseconds
        Throws:
        IllegalStateException - thrown if the cluster service is not running or has stopped

      • getOldestMember

        Member getOldestMember()
        Returns a Member object representing the senior cluster member.
        Returns:
        the senior cluster member
        Throws:
        IllegalStateException - thrown if the cluster service is not running or has stopped

      • getManagement

        Registry getManagement()
        Returns the current management registry.
        Returns:
        the current management registry or null if the management is disabled on this node
        Since:
        Coherence 3.0

      • setManagement

        void setManagement​(Registry registry)
        Sets the current management registry.
        Parameters:
        registry - the management registry to use on this node
        Since:
        Coherence 3.0

      • getClusterName

        String getClusterName()
        Determine the configured name for the Cluster. This name is defined by the application, and can be used for any application-specific purpose. Furthermore, as a safety feature, when joining into a Cluster, a Member will only join it if the Cluster has the same name as the Member was configured to join.
        Returns:
        the configured name for the Cluster or null if none is configured
        Since:
        Coherence 3.2

      • registerResource

        @Deprecated
void registerResource​(String sName,
                      Disposable resource)
        Deprecated.
        Use getResourceRegistry() to manage resources.
        Registers the passed Disposable resource with the Cluster, using the specified name. There are two reasons to register a resource:
        • Subsequent calls to getResource(String) using the same name will return the registered resource, and
        • The Cluster will invoke the Disposable.dispose() method of the resource when the Cluster is shut down; specifically, when the Cluster is shutting down, after it has shut down all of the running services, the Cluster calls Disposable.dispose() on each registered resource.

        If a resource is already registered under the specified name, and the new resource to register is not the same resource (the same reference) as the previously registered resource, then the Cluster will throw an IllegalStateException.

        To unregister a previously registered resource, call the unregisterResource(String) method with the name of the resource to unregister.

        Note: It is the responsibility of the caller to manage concurrent access to the getResource(java.lang.String), unregisterResource(String) and registerResource methods of the Cluster. Specifically, while the Cluster manages the registry of resources in a thread-safe manner, it is possible for a thread to call getResource, get a null return value because a resource had not yet been registered under the specified name, but by the time the thread instantiates a resource and attempts to register it by calling registerResource, another thread may have already done the same thing.

        Parameters:
        sName - the name of the resource
        resource - the Disposable resource to register
        Throws:
        IllegalStateException - if the resource is null
        Since:
        Coherence 3.7

      • unregisterResource

        @Deprecated
Disposable unregisterResource​(String sName)
        Deprecated.
        Use getResourceRegistry() to manage resources.
        Unregisters a resource with the specified name.

        Note: It is the responsibility of the caller to manage concurrent access to the getResource(java.lang.String), unregisterResource(String) and registerResource(java.lang.String, com.oracle.coherence.common.base.Disposable) methods of the Cluster. Specifically, while the Cluster manages the registry of resources in a thread-safe manner, it is possible for a thread to call getResource, get a null return value because a resource had not yet been registered under the specified name, but by the time the thread instantiates a resource and attempts to register it by calling registerResource, another thread may have already done the same thing.

        Parameters:
        sName - the name of the resource
        Returns:
        the registered Disposable resource or null if none was registered under that name
        Since:
        Coherence 3.7

      • getResourceRegistry

        ResourceRegistry getResourceRegistry()
        Retrieves a Cluster scoped ResourceRegistry. The resource registry is used to:
        • Register resources with the Cluster and make them accessible to the cluster.
        • Dispose of resources when the Cluster is shut down; see the ResourceRegistry API for details on how to enable cleanup of resources.
        Returns:
        a Cluster scoped resource registry
        Since:
        Coherence 12.1.2

      • getDependencies

        ClusterDependencies getDependencies()
        Retrieve the Cluster configuration.
        Returns:
        the Cluster configuration
        Since:
        Coherence 12.2.1

      • setDependencies

        void setDependencies​(ClusterDependencies deps)
        Configure the Cluster.

        This method can only be called before the Cluster is started.

        Parameters:
        deps - the dependencies object carrying the Cluster configuration information
        Throws:
        IllegalStateException - thrown if the Cluster is already running
        IllegalArgumentException - thrown if the configuration information is invalid
        Since:
        Coherence 12.1.3

      • getServiceBanner

        default String getServiceBanner()
        Return a description of the running services in this Cluster.
        Returns:
        string containing a description of the running services