Package org.jivesoftware.openfire.cluster

Class ClusterManager

  • public class ClusterManager
extends Object
    A cluster manager is responsible for triggering events related to clustering. A future version will also provide statistics about the cluster.
    Author:
    Gaston Dombiak

    • Field Detail

      • CLUSTER_PROPERTY_NAME

        public static String CLUSTER_PROPERTY_NAME

    • Constructor Detail

      • ClusterManager

        public ClusterManager()

    • Method Detail

      • addListener

        public static void addListener​(ClusterEventListener listener)
        Registers a listener to receive events.
        Parameters:
        listener - the listener.

      • addListener

        public static void addListener​(ClusterEventListener listener,
                               int sequence)
        Registers a listener to receive events, defining the order in which listeners are invoked.
        Parameters:
        listener - the listener.
        sequence - defines the order of listener invocation.

      • removeListener

        public static void removeListener​(ClusterEventListener listener)
        Unregisters a listener to receive events.
        Parameters:
        listener - the listener.

      • fireJoinedCluster

        public static void fireJoinedCluster​(boolean asynchronous)
        Triggers event indicating that this JVM is now part of a cluster. At this point the XMPPServer.getNodeID() holds the new nodeID value and the old nodeID value is passed in case the listener needs it.

        When joining the cluster as the senior cluster member the fireMarkedAsSeniorClusterMember() event will be sent right after this event.

        This event will be triggered in another thread. This will avoid potential deadlocks in Coherence.
        Parameters:
        asynchronous - true if event will be triggered in background

      • fireJoinedCluster

        public static void fireJoinedCluster​(byte[] nodeID,
                                     boolean asynchronous)
        Triggers event indicating that another JVM is now part of a cluster.

        This event will be triggered in another thread. This will avoid potential deadlocks in Coherence.

        Parameters:
        nodeID - nodeID assigned to the JVM when joining the cluster.
        asynchronous - true if event will be triggered in background

      • fireLeftCluster

        public static void fireLeftCluster()
        Triggers event indicating that this JVM is no longer part of the cluster. This could happen when disabling clustering support or removing the enterprise plugin that provides clustering support.

        Moreover, if we were in a "split brain" scenario (ie. separated cluster islands) and the island were this JVM belonged was marked as "old" then all nodes of that island will get the left cluster event and joined cluster events. That means that caches will be reset and thus will need to be repopulated again with fresh data from this JVM. This also includes the case where this JVM was the senior cluster member and when the islands met again then this JVM stopped being the senior member.

      • fireLeftCluster

        public static void fireLeftCluster​(byte[] nodeID)
        Triggers event indicating that another JVM is no longer part of the cluster. This could happen when disabling clustering support or removing the enterprise plugin that provides clustering support.
        Parameters:
        nodeID - nodeID assigned to the JVM when joining the cluster.

      • fireMarkedAsSeniorClusterMember

        public static void fireMarkedAsSeniorClusterMember()
        Triggers event indicating that this JVM is now the senior cluster member. This could either happen when initially joining the cluster or when the senior cluster member node left the cluster and this JVM was marked as the new senior cluster member.

        Moreover, in the case of a "split brain" scenario (ie. separated cluster islands) each island will have its own senior cluster member. However, when the islands meet again there could only be one senior cluster member so one of the senior cluster members will stop playing that role. When that happens the JVM no longer playing that role will receive the fireLeftCluster() and fireJoinedCluster(boolean) events.

        This event will be triggered in another thread. This will avoid potential deadlocks in Coherence.

      • startup

        public static void startup()
        Starts the cluster service if clustering is enabled. The process of starting clustering will recreate caches as distributed caches.

      • shutdown

        public static void shutdown()
        Shuts down the clustering service. This method should be called when the system is shutting down or clustering has been disabled. Failing to call this method may temporarily impact cluster performance, as the system will have to do extra work to recover from a non-clean shutdown. If clustering is not enabled, this method will do nothing.

      • setClusteringEnabled

        public static void setClusteringEnabled​(boolean enabled)
        Sets true if clustering support is enabled. An attempt to start or join an existing cluster will be attempted in the service was enabled. On the other hand, if disabled then this JVM will leave or stop the cluster.
        Parameters:
        enabled - if clustering support is enabled.

      • isClusteringEnabled

        public static boolean isClusteringEnabled()
        Returns true if clustering support is enabled. This does not mean that clustering has started or that clustering will be able to start.
        Returns:
        true if clustering support is enabled.

      • isClusteringAvailable

        public static boolean isClusteringAvailable()
        Returns true if clustering is installed and can be used by this JVM to join a cluster. A false value could mean that either clustering support is not available or the license does not allow to have more than 1 cluster node.
        Returns:
        true if clustering is installed and can be used by this JVM to join a cluster.

      • isClusteringStarting

        public static boolean isClusteringStarting()
        Returns true is clustering is currently being started. Once the cluster is started or failed to be started this value will be false.
        Returns:
        true is clustering is currently being started.

      • isClusteringStarted

        public static boolean isClusteringStarted()
        Returns true if this JVM is part of a cluster. The cluster may have many nodes or this JVM could be the only node.
        Returns:
        true if this JVM is part of a cluster.

      • isSeniorClusterMember

        public static boolean isSeniorClusterMember()
        Returns true if this member is the senior member in the cluster. If clustering is not enabled, this method will also return true. This test is useful for tasks that should only be run on a single member in a cluster.
        Returns:
        true if this cluster member is the senior or if clustering is not enabled.

        Important: If clustering is enabled but has not yet started, this may return an incorrect result

        See Also:
        isSeniorClusterMemberOrNotClustered()

      • getNodesInfo

        public static Collection<ClusterNodeInfo> getNodesInfo()
        Returns basic information about the current members of the cluster or an empty collection if not running in a cluster.
        Returns:
        information about the current members of the cluster or an empty collection if not running in a cluster.

      • getNodeInfo

        public static Optional<ClusterNodeInfo> getNodeInfo​(byte[] nodeID)
        Returns basic information about a specific member of the cluster.
        Parameters:
        nodeID - the node whose information is required
        Returns:
        the node specific information, or Optional.empty() if the node could not be identified
        Since:
        Openfire 4.4

      • getNodeInfo

        public static Optional<ClusterNodeInfo> getNodeInfo​(NodeID nodeID)
        Returns basic information about a specific member of the cluster.
        Parameters:
        nodeID - the node whose information is required
        Returns:
        the node specific information, or Optional.empty() if the node could not be identified
        Since:
        Openfire 4.4

      • getPluginAndOpenfireVersions

        public static Map<String,​Map<NodeID,​String>> getPluginAndOpenfireVersions()
        Returns the versions of plugins installed on all nodes in the cluster. If, for some reason, the version information can not be retrieved from some remote node, that node will be missing entirely from the result. The openfire version is included in the result as well, under the key "Openfire".
        Returns:
        A map of maps, containing pluginName -> (nodeId -> pluginVersion)

      • findRemotePluginsWithDifferentVersion

        public static Map<NodeID,​String> findRemotePluginsWithDifferentVersion​(String pluginName)
        Inspects whether the version of a specific plugin on remote nodes differs from the version installed locally. When the remote node has the same version of the plugin installed, the returned map will not include the NodeID of that node. When the remote node has a different version of the plugin installed, the returned map will include a NodeID entry that maps to the version identifier of the plugin that is installed on that node. When the remote node does not have the plugin installed, the returned map will contain an entry that has a null value.
        Parameters:
        pluginName - The (full) name of the plugin to check.
        Returns:
        A map containing the nodeID that has a different version of this plugin.

      • getMaxClusterNodes

        public static int getMaxClusterNodes()
        Returns the maximum number of cluster members allowed. Both values 0 and 1 mean that clustering is not available. However, a value of 1 means that it's a license problem rather than not having the ability to do clustering as defined with value 0.
        Returns:
        the maximum number of cluster members allowed or 0 or 1 if clustering is not allowed.

      • getSeniorClusterMember

        public static NodeID getSeniorClusterMember()
        Returns the id of the node that is the senior cluster member. When not in a cluster the returned node id will be the XMPPServer.getNodeID().
        Returns:
        the id of the node that is the senior cluster member.

      • isClusterMember

        public static boolean isClusterMember​(byte[] nodeID)
        Returns true if the specified node ID belongs to a known cluster node of this cluster.
        Parameters:
        nodeID - the ID of the node to verify.
        Returns:
        true if the specified node ID belongs to a known cluster node of this cluster.

      • waitForClusteringToStart

        public static void waitForClusteringToStart()
                                     throws InterruptedException
        If clustering is enabled, this method will wait until clustering is fully started.
        If clustering is not enabled, this method will return immediately.

        Important: because this method blocks the current thread, it must not be called from a plugin constructor or Plugin.initializePlugin(org.jivesoftware.openfire.container.PluginManager, java.io.File). This is because the Hazelcast clustering plugin waits until all plugins have initialised before starting, so a plugin cannot wait until clustering has started during initialisation.

        Throws:
        InterruptedException - if the thread is interrupted whilst waiting for clustering to start
        Since:
        Openfire 4.3.0

      • isSeniorClusterMemberOrNotClustered

        public static boolean isSeniorClusterMemberOrNotClustered()
        Returns true if this member is the senior member in the cluster. If clustering is not enabled, this method will also return true. This test is useful for tasks that should only be run on a single member in a cluster. Unlike isSeniorClusterMember() this method will block, if necessary, until clustering has completed initialisation. For that reason, do not call in a plugin creation or initialisation stage.
        Returns:
        true if this cluster member is the senior or if clustering is not enabled.
        Since:
        Openfire 4.3.0
        See Also:
        isSeniorClusterMember()