Interface ClusterUtilityService


  • public interface ClusterUtilityService
    The ClusterUtilityService provided utility methods to retrieve information about the nodes that make up the cluster and to broadcast events from one node to the other.
    Author:
    ivol
    • Method Detail

      • getClusterNode

        ClusterNode getClusterNode()
        Create a ClusterNode object for the cluster node on which this method is invoked.
        Returns:
        ClusterNode object for the cluster node on which this method is invoked
      • getClusterNodes

        List<ClusterNode> getClusterNodes()
                                   throws ClusterServiceException
        Returns a list of active cluster nodes. The list contains all nodes in the cluster on which the Cluster utility service is running and has recently broadcasted an 'alive' event (by default this is; in the past 2 times the clusternode_registration_heartbeat_ms as configured in web/setup). Use the method getClusterNodes with long parameter instead to retrieve cluster nodes from which a heartbeat was detected in the specified amount of milliseconds. If the Cluster utility service is not enabled in web/setup, this method throws a UtilityServiceException.
        Returns:
        Array of all active cluster nodes.
        Throws:
        ClusterServiceException - if the Cluster utility service is not enabled in web/setup
      • getClusterNodes

        List<ClusterNode> getClusterNodes​(long heartbeatReceivedSince)
                                   throws ClusterServiceException
        Returns a list of active cluster nodes. The list contains all nodes in the cluster on which the Cluster utility service is running and has broadcasted an 'alive' event no more then the specified amount of milliseconds ago. If the Cluster utility service is not enabled in web/setup, this method throws a UtilityServiceException.
        Parameters:
        heartbeatReceivedSince - Amount of milliseconds ago from which returned cluster nodes should have broadcasted an 'alive' event.
        Returns:
        Array of all active cluster nodes.
        Throws:
        ClusterServiceException - if the Cluster utility service is not enabled in web/setup
      • getClusterNodesActiveOrInactive

        List<ClusterNode> getClusterNodesActiveOrInactive()
                                                   throws ClusterServiceException
        Returns a list of ALL cluster nodes defined in the database, property isActive is set according to the state in the database table and whether or not the heartbeat requirements are met.
        Returns:
        Array of all cluster nodes active or inactive.
        Throws:
        ClusterServiceException - if the Cluster utility service is not enabled in web/setup
      • getBackendClusterNodes

        List<ClusterNode> getBackendClusterNodes()
                                          throws ClusterServiceException
        Same as getClusterNodes(). However, this method returns only the subset of cluster nodes which are not read only (so they run in backend mode).
        Returns:
        Array of all active backend cluster nodes.
        Throws:
        ClusterServiceException - if the Cluster utility service is not enabled in web/setup
      • getFrontendClusterNodes

        List<ClusterNode> getFrontendClusterNodes()
                                           throws ClusterServiceException
        Same as getClusterNodes(). However, this method returns only the subset of cluster nodes which are read only (so they run in frontend mode).
        Returns:
        Array of all active frontend cluster nodes.
        Throws:
        ClusterServiceException - if the Cluster utility service is not enabled in web/setup
      • getTaskMasterClusterNode

        ClusterNode getTaskMasterClusterNode()
                                      throws ClusterServiceException
        Same as getClusterNodes(). However, this method returns only the cluster node that is currently running in task master mode (the backend node on which most scheduled jobs are executed).
        Returns:
        The current active task master node, if available. May return null in case there is currently no active task master. Note that even a single node cluster may not have a task master; immediately after starting this server it is not running as task master, it becomes task master after a few minutes.
        Throws:
        ClusterServiceException - if the Cluster utility service is not enabled in web/setup
      • getMasterClusterNode

        ClusterNode getMasterClusterNode()
                                  throws ClusterServiceException
        This method returns the first available backend cluster node, determined by sorting the cluster ids alphabetically and taking the first entry. Note that this method still may return null, in case there is no backend node available in the cluster (i.e. only a frontend server is running).
        Returns:
        The first available backend node (called the master node), if available. May return null.
        Throws:
        ClusterServiceException - if the Cluster utility service is not enabled in web/setup
      • isMasterClusterNode

        boolean isMasterClusterNode()
                             throws ClusterServiceException
        Returns true if the cluster node returned by getMasterClusterNode() is the same as the cluster node on which this method is executed. When getMasterClusterNode() returns no node and the current node is a backend node, this method also returns true. In all other cases, it returns false; This method provides the best available check to ensure code is executed on the first available backend node. In a running cluster, this method returns true on the backend node with the alphabetically lowest clusterid. In case of cluster maintenance, this method also returns true on the first backend server that is started, before any cluster node is marked as 'active' by the cluster heartbeat thread. The only case in which it could possibly return false is when in a cluster with two backend nodes one backend node is restarted, and just before this server begins with starting the WCBs the other backend node is stopped. In this case that server is still being server comes up within 2 times the cluster heartbeat thread (2 minutes)

        This is the only proper check to use in onStart() when initializing tables, configuration, etc.

        Returns:
        true if the cluster node returned by getMasterClusterNode() is the same as the cluster node on which this method is executed
        Throws:
        ClusterServiceException
      • sendClusterEvent

        ClusterEventHandle sendClusterEvent​(Class<?> service,
                                            ClusterEventParameter argument,
                                            boolean asynchronous)
                                     throws ClusterServiceException
        Sends an event to each available cluster node. This service must be an OSGi service implementing ClusterEventListener. This invocation can be synchronous or asynchronous. For asynchronous calls, the method returns immediately after which the events will be received by the cluster nodes with a maximum delay as specified by clusternode_eventlistener_heartbeat_ms in web/setup. If more then 1 instances of the service are available, the event is only triggered on the first available instance and a warning message is logged.
        Parameters:
        service - The service to invoke
        argument - Argument to pass to the ClusterEventListener.onEvent method
        Returns:
        handle to the event, including information about the event that has been sent and the return values
        Throws:
        ClusterServiceException - In case the event could not be delivered
      • createEventParameter

        ClusterEventParameter createEventParameter()
        Creates a new instance of a ClusterEventParameter.
        Returns:
        the new ClusterEventParameter
      • createEventReturnValue

        ClusterEventReturnValue createEventReturnValue()
        Creates a new instance of a ClusterReturnValue.
        Returns:
        the new ClusterReturnValue