SimpleTcpCluster (Apache Tomcat 10.0.27 API Documentation)

Package org.apache.catalina.ha.tcp

## Class SimpleTcpCluster

- java.lang.Object
- - org.apache.catalina.util.LifecycleBase
  - - org.apache.catalina.util.LifecycleMBeanBase
    - - org.apache.catalina.ha.tcp.SimpleTcpCluster

- All Implemented Interfaces:
    `javax.management.MBeanRegistration`, `Cluster`, `Contained`, `CatalinaCluster`, `JmxEnabled`, `Lifecycle`, `ChannelListener`, `MembershipListener`

      public class SimpleTcpCluster
      extends LifecycleMBeanBase
      implements CatalinaCluster, MembershipListener, ChannelListener

  A Cluster implementation using simple multicast. Responsible for setting up a cluster and provides callers with a valid multicast receiver/sender. FIXME wrote testcases
  Author:
    Remy Maucherat, Peter Rossbach

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

      `Lifecycle.SingleUse`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `AFTER_MANAGERREGISTER_EVENT` |
    `static java.lang.String` | `AFTER_MANAGERUNREGISTER_EVENT` |
    `static java.lang.String` | `AFTER_MEMBERREGISTER_EVENT` |
    `static java.lang.String` | `AFTER_MEMBERUNREGISTER_EVENT` |
    `static java.lang.String` | `BEFORE_MANAGERREGISTER_EVENT` |
    `static java.lang.String` | `BEFORE_MANAGERUNREGISTER_EVENT` |
    `static java.lang.String` | `BEFORE_MEMBERREGISTER_EVENT` |
    `static java.lang.String` | `BEFORE_MEMBERUNREGISTER_EVENT` |
    `protected Channel` | `channel` | Group channel.
    `protected java.util.List<ClusterListener>` | `clusterListeners` | Listeners of messages
    `protected java.lang.String` | `clusterName` | The cluster name to join
    `protected Container` | `container` | The Container associated with this Cluster.
    `protected boolean` | `hasMembers` | has members
    `protected boolean` | `heartbeatBackgroundEnabled` | call Channel.heartbeat() at container background thread
    `static Log` | `log` |
    `protected java.util.Map<java.lang.String,​ClusterManager>` | `managers` | The context name <-> manager association for distributed contexts.
    `protected ClusterManager` | `managerTemplate` |
    `static java.lang.String` | `RECEIVE_MESSAGE_FAILURE_EVENT` |
    `static java.lang.String` | `SEND_MESSAGE_FAILURE_EVENT` |
    `protected static StringManager` | `sm` | The string manager for this package.
    `protected java.beans.PropertyChangeSupport` | `support` | The property change support for this component.

    - ### Fields inherited from interface org.apache.catalina.Lifecycle

      `AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SimpleTcpCluster()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `accept​(java.io.Serializable msg, Member sender)` | notify all listeners from receiving a new message is not ClusterMessage emit Failure Event to LifecycleListener
    `void` | `addClusterListener​(ClusterListener listener)` | Add cluster message listener and register cluster to this listener.
    `void` | `addValve​(Valve valve)` | Add cluster valve Cluster Valves are only add to container when cluster is started!
    `void` | `backgroundProcess()` | Execute a periodic task, such as reloading, etc.
    `protected void` | `checkDefaults()` |
    `Manager` | `createManager​(java.lang.String name)` | Create new Manager without add to cluster (comes with start the manager)
    `protected void` | `destroyInternal()` | Sub-classes wishing to perform additional clean-up should override this method, ensuring that super.destroyInternal() is the last call in the overriding method.
    `ClusterListener[]` | `findClusterListeners()` | Get the cluster listeners associated with this cluster.
    `Channel` | `getChannel()` |
    `int` | `getChannelSendOptions()` |
    `java.lang.String` | `getChannelSendOptionsName()` | returns the SendOptions as a comma separated list of names for use by JMX
    `int` | `getChannelStartOptions()` |
    `ClusterDeployer` | `getClusterDeployer()` |
    `java.lang.String` | `getClusterName()` | Return the name of the cluster that this Server is currently configured to operate within.
    `Container` | `getContainer()` | Get the Container associated with our Cluster
    `protected java.lang.String` | `getDomainInternal()` | Method implemented by sub-classes to identify the domain in which MBeans should be registered.
    `Member` | `getLocalMember()` | Return the member that represents this node.
    `Manager` | `getManager​(java.lang.String name)` | Get Manager
    `java.lang.String` | `getManagerName​(java.lang.String name, Manager manager)` | Get a new cluster name for a manager.
    `java.util.Map<java.lang.String,​ClusterManager>` | `getManagers()` |
    `ClusterManager` | `getManagerTemplate()` |
    `Member[]` | `getMembers()` | Get all current cluster members
    `protected java.lang.String` | `getObjectNameKeyProperties()` | Allow sub-classes to specify the key properties component of the `ObjectName` that will be used to register this component.
    `Valve[]` | `getValves()` | get all cluster valves
    `boolean` | `hasMembers()` |
    `protected void` | `initInternal()` | Sub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.
    `boolean` | `isHeartbeatBackgroundEnabled()` | Return heartbeat enable flag (default false)
    `boolean` | `isNotifyLifecycleListenerOnFailure()` |
    `void` | `memberAdded​(Member member)` | New cluster member is registered
    `void` | `memberDisappeared​(Member member)` | Cluster member is gone
    `void` | `messageReceived​(java.io.Serializable message, Member sender)` | Receive a message from the channel
    `void` | `messageReceived​(ClusterMessage message)` |
    `protected void` | `registerClusterValve()` | register all cluster valve to host or engine
    `void` | `registerManager​(Manager manager)` | Register a manager with the cluster.
    `void` | `removeClusterListener​(ClusterListener listener)` | Remove message listener and deregister Cluster from listener.
    `void` | `removeManager​(Manager manager)` | Remove an application from cluster replication bus.
    `void` | `send​(ClusterMessage msg)` | send message to all cluster members
    `void` | `send​(ClusterMessage msg, Member dest)` | send a cluster message to one member
    `void` | `send​(ClusterMessage msg, Member dest, int sendOptions)` | Sends a message with the specified sendOptions to a specific member in the cluster.
    `void` | `setChannel​(Channel channel)` |
    `void` | `setChannelSendOptions​(int channelSendOptions)` |
    `void` | `setChannelSendOptions​(java.lang.String channelSendOptions)` |
    `void` | `setChannelStartOptions​(int channelStartOptions)` |
    `void` | `setClusterDeployer​(ClusterDeployer clusterDeployer)` | set a new Deployer, must be set before cluster started!
    `void` | `setClusterName​(java.lang.String clusterName)` | Set the name of the cluster to join, if no cluster with this name is present create one.
    `void` | `setContainer​(Container container)` | Set the Container associated with our Cluster
    `void` | `setHeartbeatBackgroundEnabled​(boolean heartbeatBackgroundEnabled)` | enabled that container backgroundThread call heartbeat at channel
    `void` | `setManagerTemplate​(ClusterManager managerTemplate)` |
    `void` | `setNotifyLifecycleListenerOnFailure​(boolean notifyListenerOnFailure)` |
    `protected void` | `startInternal()` | Start Cluster and implement the requirements of `LifecycleBase.startInternal()`.
    `protected void` | `stopInternal()` | Stop Cluster and implement the requirements of `LifecycleBase.stopInternal()`.
    `java.lang.String` | `toString()` | Return a String rendering of this object.
    `protected void` | `unregisterClusterValve()` | unregister all cluster valve to host or engine

    - ### Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

      `getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister`

    - ### Methods inherited from class org.apache.catalina.util.LifecycleBase

      `addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.apache.catalina.tribes.ChannelListener

      `equals, hashCode`

- - ### Field Detail

    - #### log

          public static final Log log

    - #### BEFORE_MEMBERREGISTER_EVENT

          public static final java.lang.String BEFORE_MEMBERREGISTER_EVENT

      See Also:
        Constant Field Values

    - #### AFTER_MEMBERREGISTER_EVENT

          public static final java.lang.String AFTER_MEMBERREGISTER_EVENT

      See Also:
        Constant Field Values

    - #### BEFORE_MANAGERREGISTER_EVENT

          public static final java.lang.String BEFORE_MANAGERREGISTER_EVENT

      See Also:
        Constant Field Values

    - #### AFTER_MANAGERREGISTER_EVENT

          public static final java.lang.String AFTER_MANAGERREGISTER_EVENT

      See Also:
        Constant Field Values

    - #### BEFORE_MANAGERUNREGISTER_EVENT

          public static final java.lang.String BEFORE_MANAGERUNREGISTER_EVENT

      See Also:
        Constant Field Values

    - #### AFTER_MANAGERUNREGISTER_EVENT

          public static final java.lang.String AFTER_MANAGERUNREGISTER_EVENT

      See Also:
        Constant Field Values

    - #### BEFORE_MEMBERUNREGISTER_EVENT

          public static final java.lang.String BEFORE_MEMBERUNREGISTER_EVENT

      See Also:
        Constant Field Values

    - #### AFTER_MEMBERUNREGISTER_EVENT

          public static final java.lang.String AFTER_MEMBERUNREGISTER_EVENT

      See Also:
        Constant Field Values

    - #### SEND_MESSAGE_FAILURE_EVENT

          public static final java.lang.String SEND_MESSAGE_FAILURE_EVENT

      See Also:
        Constant Field Values

    - #### RECEIVE_MESSAGE_FAILURE_EVENT

          public static final java.lang.String RECEIVE_MESSAGE_FAILURE_EVENT

      See Also:
        Constant Field Values

    - #### channel

          protected Channel channel

      Group channel.

    - #### sm

          protected static final StringManager sm

      The string manager for this package.

    - #### clusterName

          protected java.lang.String clusterName

      The cluster name to join

    - #### heartbeatBackgroundEnabled

          protected boolean heartbeatBackgroundEnabled

      call Channel.heartbeat() at container background thread
      See Also:
        `GroupChannel.heartbeat()`

    - #### container

          protected Container container

      The Container associated with this Cluster.

    - #### support

          protected final java.beans.PropertyChangeSupport support

      The property change support for this component.

    - #### managers

          protected final java.util.Map<java.lang.String,​ClusterManager> managers

      The context name <-> manager association for distributed contexts.

    - #### managerTemplate

          protected ClusterManager managerTemplate

    - #### clusterListeners

          protected final java.util.List<ClusterListener> clusterListeners

      Listeners of messages

    - #### hasMembers

          protected boolean hasMembers

      has members

  - ### Constructor Detail

    - #### SimpleTcpCluster

          public SimpleTcpCluster()

  - ### Method Detail

    - #### isHeartbeatBackgroundEnabled

          public boolean isHeartbeatBackgroundEnabled()

      Return heartbeat enable flag (default false)
      Returns:
        the heartbeatBackgroundEnabled

    - #### setHeartbeatBackgroundEnabled

          public void setHeartbeatBackgroundEnabled​(boolean heartbeatBackgroundEnabled)

      enabled that container backgroundThread call heartbeat at channel
      Parameters:
        `heartbeatBackgroundEnabled` - the heartbeatBackgroundEnabled to set

    - #### setClusterName

          public void setClusterName​(java.lang.String clusterName)

      Set the name of the cluster to join, if no cluster with this name is present create one.
      Specified by:
        `setClusterName` in interface `Cluster`
      Parameters:
        `clusterName` - The clustername to join

    - #### getClusterName

          public java.lang.String getClusterName()

      Return the name of the cluster that this Server is currently configured to operate within.
      Specified by:
        `getClusterName` in interface `Cluster`
      Returns:
        The name of the cluster associated with this server

    - #### setContainer

          public void setContainer​(Container container)

      Set the Container associated with our Cluster
      Specified by:
        `setContainer` in interface `Contained`
      Parameters:
        `container` - The Container to use

    - #### getContainer

          public Container getContainer()

      Get the Container associated with our Cluster
      Specified by:
        `getContainer` in interface `Contained`
      Returns:
        The Container associated with our Cluster

    - #### isNotifyLifecycleListenerOnFailure

          public boolean isNotifyLifecycleListenerOnFailure()

      Returns:
        Returns the notifyLifecycleListenerOnFailure.

    - #### setNotifyLifecycleListenerOnFailure

          public void setNotifyLifecycleListenerOnFailure​(boolean notifyListenerOnFailure)

      Parameters:
        `notifyListenerOnFailure` - The notifyLifecycleListenerOnFailure to set.

    - #### addValve

          public void addValve​(Valve valve)

      Add cluster valve Cluster Valves are only add to container when cluster is started!
      Specified by:
        `addValve` in interface `CatalinaCluster`
      Parameters:
        `valve` - The new cluster Valve.

    - #### getValves

          public Valve[] getValves()

      get all cluster valves
      Specified by:
        `getValves` in interface `CatalinaCluster`
      Returns:
        current cluster valves

    - #### findClusterListeners

          public ClusterListener[] findClusterListeners()

      Get the cluster listeners associated with this cluster. If this Array has no listeners registered, a zero-length array is returned.
      Returns:
        the listener array

    - #### addClusterListener

          public void addClusterListener​(ClusterListener listener)

      Add cluster message listener and register cluster to this listener.
      Specified by:
        `addClusterListener` in interface `CatalinaCluster`
      Parameters:
        `listener` - The new listener
      See Also:
        `CatalinaCluster.addClusterListener(org.apache.catalina.ha.ClusterListener)`

    - #### removeClusterListener

          public void removeClusterListener​(ClusterListener listener)

      Remove message listener and deregister Cluster from listener.
      Specified by:
        `removeClusterListener` in interface `CatalinaCluster`
      Parameters:
        `listener` - The listener to remove
      See Also:
        `CatalinaCluster.removeClusterListener(org.apache.catalina.ha.ClusterListener)`

    - #### getClusterDeployer

          public ClusterDeployer getClusterDeployer()

      Specified by:
        `getClusterDeployer` in interface `CatalinaCluster`
      Returns:
        the current Deployer

    - #### setClusterDeployer

          public void setClusterDeployer​(ClusterDeployer clusterDeployer)

      set a new Deployer, must be set before cluster started!
      Specified by:
        `setClusterDeployer` in interface `CatalinaCluster`
      Parameters:
        `clusterDeployer` - The associated deployer

    - #### setChannel

          public void setChannel​(Channel channel)

      Specified by:
        `setChannel` in interface `CatalinaCluster`

    - #### setManagerTemplate

          public void setManagerTemplate​(ClusterManager managerTemplate)

    - #### setChannelSendOptions

          public void setChannelSendOptions​(int channelSendOptions)

    - #### setChannelSendOptions

          public void setChannelSendOptions​(java.lang.String channelSendOptions)

    - #### hasMembers

          public boolean hasMembers()

      Specified by:
        `hasMembers` in interface `CatalinaCluster`
      Returns:
        `true` if the cluster has members.

    - #### getMembers

          public Member[] getMembers()

      Get all current cluster members
      Specified by:
        `getMembers` in interface `CatalinaCluster`
      Returns:
        all members or empty array

    - #### getLocalMember

          public Member getLocalMember()

      Return the member that represents this node.
      Specified by:
        `getLocalMember` in interface `CatalinaCluster`
      Returns:
        Member

    - #### getManagers

          public java.util.Map<java.lang.String,​ClusterManager> getManagers()

      Specified by:
        `getManagers` in interface `CatalinaCluster`
      Returns:
        Returns the managers.

    - #### getChannel

          public Channel getChannel()

      Specified by:
        `getChannel` in interface `CatalinaCluster`

    - #### getManagerTemplate

          public ClusterManager getManagerTemplate()

    - #### getChannelSendOptions

          public int getChannelSendOptions()

    - #### getChannelSendOptionsName

          public java.lang.String getChannelSendOptionsName()

      returns the SendOptions as a comma separated list of names for use by JMX
      Returns:
        a comma separated list of the option names

    - #### createManager

          public Manager createManager​(java.lang.String name)

      Create new Manager without add to cluster (comes with start the manager)
      Specified by:
        `createManager` in interface `Cluster`
      Parameters:
        `name` - Context Name of this manager
      Returns:
        The newly created Manager instance
      See Also:
        `Cluster.createManager(java.lang.String)`, `LifecycleBase.start()`

    - #### registerManager

          public void registerManager​(Manager manager)

      Description copied from interface: `Cluster`
      Register a manager with the cluster. If the cluster is not responsible for creating a manager, then the container will at least notify the cluster that this manager is participating in the cluster.
      Specified by:
        `registerManager` in interface `Cluster`
      Parameters:
        `manager` - Manager

    - #### removeManager

          public void removeManager​(Manager manager)

      Remove an application from cluster replication bus.
      Specified by:
        `removeManager` in interface `Cluster`
      Parameters:
        `manager` - The manager
      See Also:
        `Cluster.removeManager(Manager)`

    - #### getManagerName

          public java.lang.String getManagerName​(java.lang.String name,
                                                 Manager manager)

      Description copied from interface: `CatalinaCluster`
      Get a new cluster name for a manager.
      Specified by:
        `getManagerName` in interface `CatalinaCluster`
      Parameters:
        `name` - Override name (optional)
        `manager` - The manager
      Returns:
        the manager name in the cluster

    - #### getManager

          public Manager getManager​(java.lang.String name)

      Description copied from interface: `CatalinaCluster`
      Get Manager
      Specified by:
        `getManager` in interface `CatalinaCluster`
      Parameters:
        `name` - The manager name
      Returns:
        The manager

    - #### backgroundProcess

          public void backgroundProcess()

      Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of this container. Unexpected throwables will be caught and logged.
      Specified by:
        `backgroundProcess` in interface `Cluster`
      See Also:
        `FarmWarDeployer.backgroundProcess()`, `GroupChannel.heartbeat()`

    - #### initInternal

          protected void initInternal()
                               throws LifecycleException

      Description copied from class: `LifecycleMBeanBase`
      Sub-classes wishing to perform additional initialization should override this method, ensuring that super.initInternal() is the first call in the overriding method.
      Overrides:
        `initInternal` in class `LifecycleMBeanBase`
      Throws:
        `LifecycleException` - If the initialisation fails

    - #### startInternal

          protected void startInternal()
                                throws LifecycleException

      Start Cluster and implement the requirements of `LifecycleBase.startInternal()`.
      Specified by:
        `startInternal` in class `LifecycleBase`
      Throws:
        `LifecycleException` - if this component detects a fatal error that prevents this component from being used

    - #### checkDefaults

          protected void checkDefaults()

    - #### registerClusterValve

          protected void registerClusterValve()

      register all cluster valve to host or engine

    - #### unregisterClusterValve

          protected void unregisterClusterValve()

      unregister all cluster valve to host or engine

    - #### stopInternal

          protected void stopInternal()
                               throws LifecycleException

      Stop Cluster and implement the requirements of `LifecycleBase.stopInternal()`.
      Specified by:
        `stopInternal` in class `LifecycleBase`
      Throws:
        `LifecycleException` - if this component detects a fatal error that prevents this component from being used

    - #### destroyInternal

          protected void destroyInternal()
                                  throws LifecycleException

      Description copied from class: `LifecycleMBeanBase`
      Sub-classes wishing to perform additional clean-up should override this method, ensuring that super.destroyInternal() is the last call in the overriding method.
      Overrides:
        `destroyInternal` in class `LifecycleMBeanBase`
      Throws:
        `LifecycleException` - If the destruction fails

    - #### toString

          public java.lang.String toString()

      Return a String rendering of this object.
      Overrides:
        `toString` in class `java.lang.Object`

    - #### send

          public void send​(ClusterMessage msg)

      send message to all cluster members
      Specified by:
        `send` in interface `CatalinaCluster`
      Parameters:
        `msg` - message to transfer
      See Also:
        `CatalinaCluster.send(org.apache.catalina.ha.ClusterMessage)`

    - #### send

          public void send​(ClusterMessage msg,
                           Member dest)

      send a cluster message to one member
      Specified by:
        `send` in interface `CatalinaCluster`
      Parameters:
        `msg` - message to transfer
        `dest` - Receiver member
      See Also:
        `CatalinaCluster.send(org.apache.catalina.ha.ClusterMessage, org.apache.catalina.tribes.Member)`

    - #### send

          public void send​(ClusterMessage msg,
                           Member dest,
                           int sendOptions)

      Description copied from interface: `CatalinaCluster`
      Sends a message with the specified sendOptions to a specific member in the cluster.
      Specified by:
        `send` in interface `CatalinaCluster`
      Parameters:
        `msg` - ClusterMessage
        `dest` - Member
        `sendOptions` - sendOptions

    - #### memberAdded

          public void memberAdded​(Member member)

      New cluster member is registered
      Specified by:
        `memberAdded` in interface `MembershipListener`
      Parameters:
        `member` - Member - the member that was added
      See Also:
        `MembershipListener.memberAdded(org.apache.catalina.tribes.Member)`

    - #### memberDisappeared

          public void memberDisappeared​(Member member)

      Cluster member is gone
      Specified by:
        `memberDisappeared` in interface `MembershipListener`
      Parameters:
        `member` - Member
      See Also:
        `MembershipListener.memberDisappeared(org.apache.catalina.tribes.Member)`

    - #### accept

          public boolean accept​(java.io.Serializable msg,
                                Member sender)

      notify all listeners from receiving a new message is not ClusterMessage emit Failure Event to LifecycleListener
      Specified by:
        `accept` in interface `ChannelListener`
      Parameters:
        `msg` - received Message
        `sender` - Member
      Returns:
        boolean

    - #### messageReceived

          public void messageReceived​(java.io.Serializable message,
                                      Member sender)

      Description copied from interface: `ChannelListener`
      Receive a message from the channel
      Specified by:
        `messageReceived` in interface `ChannelListener`
      Parameters:
        `message` - Serializable
        `sender` - - the source of the message

    - #### messageReceived

          public void messageReceived​(ClusterMessage message)

    - #### getChannelStartOptions

          public int getChannelStartOptions()

    - #### setChannelStartOptions

          public void setChannelStartOptions​(int channelStartOptions)

    - #### getDomainInternal

          protected java.lang.String getDomainInternal()

      Description copied from class: `LifecycleMBeanBase`
      Method implemented by sub-classes to identify the domain in which MBeans should be registered.
      Specified by:
        `getDomainInternal` in class `LifecycleMBeanBase`
      Returns:
        The name of the domain to use to register MBeans.

    - #### getObjectNameKeyProperties

          protected java.lang.String getObjectNameKeyProperties()

      Description copied from class: `LifecycleMBeanBase`
      Allow sub-classes to specify the key properties component of the `ObjectName` that will be used to register this component.
      Specified by:
        `getObjectNameKeyProperties` in class `LifecycleMBeanBase`
      Returns:
        The string representation of the key properties component of the desired `ObjectName`