org.apache.catalina.tribes.group

## Class GroupChannel

- java.lang.Object
- - org.apache.catalina.tribes.group.ChannelInterceptorBase
  - - org.apache.catalina.tribes.group.GroupChannel

- All Implemented Interfaces:
    MBeanRegistration, Channel, ChannelInterceptor, GroupChannelMBean, Heartbeat, JmxChannel, ManagedChannel, MembershipListener

      public class GroupChannel
      extends ChannelInterceptorBase
      implements ManagedChannel, JmxChannel, GroupChannelMBean

  The default implementation of a Channel.
  The GroupChannel manages the replication channel. It coordinates message being sent and received with membership announcements. The channel has an chain of interceptors that can modify the message or perform other logic.
  It manages a complete group, both membership and replication.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `GroupChannel.HeartbeatThread` Title: Internal heartbeat thread Description: if `Channel.getHeartbeat()==true` then a thread of this class is created
    `static class` | `GroupChannel.InterceptorIterator` Title: Interceptor Iterator Description: An iterator to loop through the interceptors in a channel

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

      `ChannelInterceptor.InterceptorEvent`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected List<ChannelListener>` | `channelListeners` A list of channel listeners that subscribe to incoming messages
    `protected ChannelCoordinator` | `coordinator` The `ChannelCoordinator` coordinates the bottom layer components: - MembershipService - ChannelSender - ChannelReceiver
    `protected GroupChannel.HeartbeatThread` | `hbthread` Internal heartbeat thread
    `protected boolean` | `heartbeat` Flag to determine if the channel manages its own heartbeat If set to true, the channel will start a local thread for the heart beat.
    `protected long` | `heartbeatSleeptime` If `heartbeat == true` then how often do we want this heartbeat to run. default is one minute
    `protected ChannelInterceptor` | `interceptors` The first interceptor in the interceptor stack.
    `protected List<MembershipListener>` | `membershipListeners` A list of membership listeners that subscribe to membership announcements
    `protected String` | `name` the name of this channel.
    `protected boolean` | `optionCheck` If set to true, the GroupChannel will check to make sure that
    `protected static StringManager` | `sm`

    - ### Fields inherited from class org.apache.catalina.tribes.group.ChannelInterceptorBase

      `optionFlag`

    - ### Fields inherited from interface org.apache.catalina.tribes.Channel

      `DEFAULT, MBR_RX_SEQ, MBR_TX_SEQ, SEND_OPTIONS_ASYNCHRONOUS, SEND_OPTIONS_BYTE_MESSAGE, SEND_OPTIONS_DEFAULT, SEND_OPTIONS_MULTICAST, SEND_OPTIONS_SECURE, SEND_OPTIONS_SYNCHRONIZED_ACK, SEND_OPTIONS_UDP, SEND_OPTIONS_USE_ACK, SND_RX_SEQ, SND_TX_SEQ`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GroupChannel()` Creates a GroupChannel.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addChannelListener(ChannelListener channelListener)` Adds a channel listener to the channel.
    `void` | `addInterceptor(ChannelInterceptor interceptor)` Adds an interceptor to the stack for message processing Interceptors are ordered in the way they are added.
    `void` | `addMembershipListener(MembershipListener membershipListener)` Adds a membership listener to the channel.
    `protected void` | `checkOptionFlags()` Validates the option flags that each interceptor is using and reports an error if two interceptor share the same flag.
    `ChannelReceiver` | `getChannelReceiver()` Returns the channel receiver component
    `ChannelSender` | `getChannelSender()` Returns the channel sender component
    `ChannelInterceptor` | `getFirstInterceptor()` Returns the first interceptor of the stack.
    `boolean` | `getHeartbeat()`
    `long` | `getHeartbeatSleeptime()` Returns the sleep time in milliseconds that the internal heartbeat will sleep in between invocations of `Channel.heartbeat()`
    `Iterator<ChannelInterceptor>` | `getInterceptors()` Returns an iterator of all the interceptors in this stack
    `String` | `getJmxDomain()` Return the jmx domain which this channel is registered.
    `String` | `getJmxPrefix()` Return the jmx prefix which will be used with channel ObjectName.
    `MembershipService` | `getMembershipService()` Returns the membership service component
    `String` | `getName()` Return the name of this channel.
    `boolean` | `getOptionCheck()`
    `void` | `heartbeat()` Sends a heartbeat through the interceptor stack.
    `boolean` | `isJmxEnabled()` If set to true, this channel is registered with jmx.
    `void` | `memberAdded(Member member)` memberAdded gets invoked by the interceptor below the channel and the channel will broadcast it to the membership listeners
    `void` | `memberDisappeared(Member member)` memberDisappeared gets invoked by the interceptor below the channel and the channel will broadcast it to the membership listeners
    `void` | `messageReceived(ChannelMessage msg)` Callback from the interceptor stack.
    `void` | `postDeregister()`
    `void` | `postRegister(Boolean registrationDone)`
    `void` | `preDeregister()`
    `ObjectName` | `preRegister(MBeanServer server, ObjectName name)`
    `void` | `removeChannelListener(ChannelListener channelListener)` Removes a channel listener from the channel.
    `void` | `removeMembershipListener(MembershipListener membershipListener)` Removes a membership listener from the channel.
    `UniqueId` | `send(Member[] destination, Serializable msg, int options)` Send a message to the destinations specified
    `UniqueId` | `send(Member[] destination, Serializable msg, int options, ErrorHandler handler)` Send a message to one or more members in the cluster
    `protected void` | `sendNoRpcChannelReply(RpcMessage msg, Member destination)` Sends a `NoRpcChannelReply` message to a member This method gets invoked by the channel if a RPC message comes in and no channel listener accepts the message.
    `void` | `setChannelReceiver(ChannelReceiver clusterReceiver)` Sets the channel receiver component
    `void` | `setChannelSender(ChannelSender clusterSender)` Sets the channel sender component
    `void` | `setHeartbeat(boolean heartbeat)` Enables or disables local heartbeat.
    `void` | `setHeartbeatSleeptime(long heartbeatSleeptime)` Configure local heartbeat sleep time Only used when `getHeartbeat()==true`
    `void` | `setJmxDomain(String jmxDomain)` Set the jmx domain which this channel should be registered.
    `void` | `setJmxEnabled(boolean jmxEnabled)` If set to true, this channel is registered with jmx.
    `void` | `setJmxPrefix(String jmxPrefix)` Set the jmx prefix which will be used with channel ObjectName.
    `void` | `setMembershipService(MembershipService membershipService)` Sets the membership component
    `void` | `setName(String name)` Set the name of this channel
    `void` | `setOptionCheck(boolean optionCheck)` Enables/disables the option check Setting this to true, will make the GroupChannel perform a conflict check on the interceptors.
    `protected void` | `setupDefaultStack()` Sets up the default implementation interceptor stack if no interceptors have been added
    `void` | `start(int svc)` Starts the channel.
    `void` | `stop(int svc)` Stops the channel.

    - ### Methods inherited from class org.apache.catalina.tribes.group.ChannelInterceptorBase

      `fireInterceptorEvent, getChannel, getLocalMember, getMember, getMembers, getNext, getOptionFlag, getPrevious, hasMembers, okToProcess, sendMessage, setChannel, setNext, setOptionFlag, setPrevious`

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

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

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

      `getLocalMember, getMember, getMembers, hasMembers`

    - ### Methods inherited from interface org.apache.catalina.tribes.group.GroupChannelMBean

      `getLocalMember, getMembers, hasMembers`

- - ### Field Detail

    - #### sm

          protected static final StringManager sm

    - #### heartbeat

          protected boolean heartbeat

      Flag to determine if the channel manages its own heartbeat If set to true, the channel will start a local thread for the heart beat.

    - #### heartbeatSleeptime

          protected long heartbeatSleeptime

      If `heartbeat == true` then how often do we want this heartbeat to run. default is one minute

    - #### hbthread

          protected GroupChannel.HeartbeatThread hbthread

      Internal heartbeat thread

    - #### coordinator

          protected final ChannelCoordinator coordinator

      The `ChannelCoordinator` coordinates the bottom layer components:
      - MembershipService
      - ChannelSender
      - ChannelReceiver

    - #### interceptors

          protected ChannelInterceptor interceptors

      The first interceptor in the interceptor stack. The interceptors are chained in a linked list, so we only need a reference to the first one

    - #### membershipListeners

          protected final List<MembershipListener> membershipListeners

      A list of membership listeners that subscribe to membership announcements

    - #### channelListeners

          protected final List<ChannelListener> channelListeners

      A list of channel listeners that subscribe to incoming messages

    - #### optionCheck

          protected boolean optionCheck

      If set to true, the GroupChannel will check to make sure that

    - #### name

          protected String name

      the name of this channel.

  - ### Constructor Detail

    - #### GroupChannel

          public GroupChannel()

      Creates a GroupChannel. This constructor will also add the first interceptor in the GroupChannel.
      The first interceptor is always the channel itself.

  - ### Method Detail

    - #### addInterceptor

          public void addInterceptor(ChannelInterceptor interceptor)

      Adds an interceptor to the stack for message processing
      Interceptors are ordered in the way they are added.
      `channel.addInterceptor(A);`
      `channel.addInterceptor(C);`
      `channel.addInterceptor(B);`
      Will result in an interceptor stack like this:
      `A -> C -> B`
      The complete stack will look like this:
      `Channel -> A -> C -> B -> ChannelCoordinator`
      Specified by:
        `addInterceptor` in interface `Channel`
      Parameters:
        `interceptor` - ChannelInterceptorBase

    - #### heartbeat

          public void heartbeat()

      Sends a heartbeat through the interceptor stack.
      Invoke this method from the application on a periodic basis if you have turned off internal heartbeats `channel.setHeartbeat(false)`
      Specified by:
        `heartbeat` in interface `Channel`
      Specified by:
        `heartbeat` in interface `ChannelInterceptor`
      Specified by:
        `heartbeat` in interface `Heartbeat`
      Overrides:
        `heartbeat` in class `ChannelInterceptorBase`
      See Also:
        `Channel.setHeartbeat(boolean)`

    - #### send

          public UniqueId send(Member[] destination,
                      Serializable msg,
                      int options)
                        throws ChannelException

      Send a message to the destinations specified
      Specified by:
        `send` in interface `Channel`
      Specified by:
        `send` in interface `GroupChannelMBean`
      Parameters:
        `destination` - Member[] - destination.length > 0
        `msg` - Serializable - the message to send
        `options` - sender options, options can trigger guarantee levels and different interceptors to react to the message see class documentation for the `Channel` object.
      Returns:
        UniqueId - the unique Id that was assigned to this message
      Throws:
        `ChannelException` - - if an error occurs processing the message
      See Also:
        `Channel`

    - #### send

          public UniqueId send(Member[] destination,
                      Serializable msg,
                      int options,
                      ErrorHandler handler)
                        throws ChannelException

      Description copied from interface: `Channel`
      Send a message to one or more members in the cluster
      Specified by:
        `send` in interface `Channel`
      Specified by:
        `send` in interface `GroupChannelMBean`
      Parameters:
        `destination` - Member[] - destination.length > 0
        `msg` - Serializable - the message to send
        `options` - sender options, options can trigger guarantee levels and different interceptors to react to the message see class documentation for the `Channel` object.
        `handler` - - callback object for error handling and completion notification, used when a message is sent asynchronously using the `Channel.SEND_OPTIONS_ASYNCHRONOUS` flag enabled.
      Returns:
        UniqueId - the unique Id that was assigned to this message
      Throws:
        `ChannelException` - - if an error occurs processing the message
      See Also:
        `Channel`

    - #### messageReceived

          public void messageReceived(ChannelMessage msg)

      Callback from the interceptor stack.
      When a message is received from a remote node, this method will be invoked by the previous interceptor.
      This method can also be used to send a message to other components within the same application, but its an extreme case, and you're probably better off doing that logic between the applications itself.
      Specified by:
        `messageReceived` in interface `ChannelInterceptor`
      Overrides:
        `messageReceived` in class `ChannelInterceptorBase`
      Parameters:
        `msg` - ChannelMessage

    - #### sendNoRpcChannelReply

          protected void sendNoRpcChannelReply(RpcMessage msg,
                                   Member destination)

      Sends a `NoRpcChannelReply` message to a member
      This method gets invoked by the channel if a RPC message comes in and no channel listener accepts the message. This avoids timeout
      Parameters:
        `msg` - RpcMessage
        `destination` - Member - the destination for the reply

    - #### memberAdded

          public void memberAdded(Member member)

      memberAdded gets invoked by the interceptor below the channel and the channel will broadcast it to the membership listeners
      Specified by:
        `memberAdded` in interface `MembershipListener`
      Overrides:
        `memberAdded` in class `ChannelInterceptorBase`
      Parameters:
        `member` - Member - the new member

    - #### memberDisappeared

          public void memberDisappeared(Member member)

      memberDisappeared gets invoked by the interceptor below the channel and the channel will broadcast it to the membership listeners
      Specified by:
        `memberDisappeared` in interface `MembershipListener`
      Overrides:
        `memberDisappeared` in class `ChannelInterceptorBase`
      Parameters:
        `member` - Member - the member that left or crashed
      See Also:
        `Member.SHUTDOWN_PAYLOAD`

    - #### setupDefaultStack

          protected void setupDefaultStack()
                                    throws ChannelException

      Sets up the default implementation interceptor stack if no interceptors have been added
      Throws:
        `ChannelException` - Cluster error

    - #### checkOptionFlags

          protected void checkOptionFlags()
                                   throws ChannelException

      Validates the option flags that each interceptor is using and reports an error if two interceptor share the same flag.
      Throws:
        `ChannelException` - Error with option flag

    - #### start

          public void start(int svc)
                     throws ChannelException

      Starts the channel.
      Specified by:
        `start` in interface `Channel`
      Specified by:
        `start` in interface `ChannelInterceptor`
      Specified by:
        `start` in interface `GroupChannelMBean`
      Overrides:
        `start` in class `ChannelInterceptorBase`
      Parameters:
        `svc` - int - what service to start
      Throws:
        `ChannelException` - Start error
      See Also:
        `Channel.start(int)`

    - #### stop

          public void stop(int svc)
                    throws ChannelException

      Stops the channel.
      Specified by:
        `stop` in interface `Channel`
      Specified by:
        `stop` in interface `ChannelInterceptor`
      Specified by:
        `stop` in interface `GroupChannelMBean`
      Overrides:
        `stop` in class `ChannelInterceptorBase`
      Parameters:
        `svc` - int
      Throws:
        `ChannelException` - Stop error
      See Also:
        `Channel.stop(int)`

    - #### getFirstInterceptor

          public ChannelInterceptor getFirstInterceptor()

      Returns the first interceptor of the stack. Useful for traversal.
      Returns:
        ChannelInterceptor

    - #### getChannelReceiver

          public ChannelReceiver getChannelReceiver()

      Returns the channel receiver component
      Specified by:
        `getChannelReceiver` in interface `ManagedChannel`
      Returns:
        ChannelReceiver
      See Also:
        `ChannelReceiver`

    - #### getChannelSender

          public ChannelSender getChannelSender()

      Returns the channel sender component
      Specified by:
        `getChannelSender` in interface `ManagedChannel`
      Returns:
        ChannelSender
      See Also:
        `ChannelSender`

    - #### getMembershipService

          public MembershipService getMembershipService()

      Returns the membership service component
      Specified by:
        `getMembershipService` in interface `ManagedChannel`
      Returns:
        MembershipService
      See Also:
        `MembershipService`

    - #### setChannelReceiver

          public void setChannelReceiver(ChannelReceiver clusterReceiver)

      Sets the channel receiver component
      Specified by:
        `setChannelReceiver` in interface `ManagedChannel`
      Parameters:
        `clusterReceiver` - ChannelReceiver
      See Also:
        `ChannelReceiver`

    - #### setChannelSender

          public void setChannelSender(ChannelSender clusterSender)

      Sets the channel sender component
      Specified by:
        `setChannelSender` in interface `ManagedChannel`
      Parameters:
        `clusterSender` - ChannelSender
      See Also:
        `ChannelSender`

    - #### setMembershipService

          public void setMembershipService(MembershipService membershipService)

      Sets the membership component
      Specified by:
        `setMembershipService` in interface `ManagedChannel`
      Parameters:
        `membershipService` - MembershipService
      See Also:
        `MembershipService`

    - #### addMembershipListener

          public void addMembershipListener(MembershipListener membershipListener)

      Adds a membership listener to the channel.
      Membership listeners are uniquely identified using the equals(Object) method
      Specified by:
        `addMembershipListener` in interface `Channel`
      Specified by:
        `addMembershipListener` in interface `GroupChannelMBean`
      Parameters:
        `membershipListener` - MembershipListener
      See Also:
        `MembershipListener`

    - #### removeMembershipListener

          public void removeMembershipListener(MembershipListener membershipListener)

      Removes a membership listener from the channel.
      Membership listeners are uniquely identified using the equals(Object) method
      Specified by:
        `removeMembershipListener` in interface `Channel`
      Specified by:
        `removeMembershipListener` in interface `GroupChannelMBean`
      Parameters:
        `membershipListener` - MembershipListener
      See Also:
        `MembershipListener`

    - #### addChannelListener

          public void addChannelListener(ChannelListener channelListener)

      Adds a channel listener to the channel.
      Channel listeners are uniquely identified using the equals(Object) method
      Specified by:
        `addChannelListener` in interface `Channel`
      Specified by:
        `addChannelListener` in interface `GroupChannelMBean`
      Parameters:
        `channelListener` - ChannelListener
      See Also:
        `ChannelListener`, `Heartbeat`

    - #### removeChannelListener

          public void removeChannelListener(ChannelListener channelListener)

      Removes a channel listener from the channel.
      Channel listeners are uniquely identified using the equals(Object) method
      Specified by:
        `removeChannelListener` in interface `Channel`
      Specified by:
        `removeChannelListener` in interface `GroupChannelMBean`
      Parameters:
        `channelListener` - ChannelListener
      See Also:
        `ChannelListener`

    - #### getInterceptors

          public Iterator<ChannelInterceptor> getInterceptors()

      Returns an iterator of all the interceptors in this stack
      Specified by:
        `getInterceptors` in interface `ManagedChannel`
      Returns:
        Iterator
      See Also:
        `Channel.addInterceptor(ChannelInterceptor)`

    - #### setOptionCheck

          public void setOptionCheck(boolean optionCheck)

      Enables/disables the option check
      Setting this to true, will make the GroupChannel perform a conflict check on the interceptors. If two interceptors are using the same option flag and throw an error upon start.
      Parameters:
        `optionCheck` - boolean

    - #### setHeartbeatSleeptime

          public void setHeartbeatSleeptime(long heartbeatSleeptime)

      Configure local heartbeat sleep time
      Only used when `getHeartbeat()==true`
      Parameters:
        `heartbeatSleeptime` - long - time in milliseconds to sleep between heartbeats

    - #### setHeartbeat

          public void setHeartbeat(boolean heartbeat)

      Enables or disables local heartbeat. if `setHeartbeat(true)` is invoked then the channel will start an internal thread to invoke `Channel.heartbeat()` every `getHeartbeatSleeptime` milliseconds
      Specified by:
        `setHeartbeat` in interface `Channel`
      Parameters:
        `heartbeat` - boolean
      See Also:
        `Channel.heartbeat()`

    - #### getOptionCheck

          public boolean getOptionCheck()

      Specified by:
        `getOptionCheck` in interface `GroupChannelMBean`
      Returns:
        boolean
      See Also:
        `setOptionCheck(boolean)`

    - #### getHeartbeat

          public boolean getHeartbeat()

      Specified by:
        `getHeartbeat` in interface `GroupChannelMBean`
      Returns:
        boolean
      See Also:
        `setHeartbeat(boolean)`

    - #### getHeartbeatSleeptime

          public long getHeartbeatSleeptime()

      Returns the sleep time in milliseconds that the internal heartbeat will sleep in between invocations of `Channel.heartbeat()`
      Specified by:
        `getHeartbeatSleeptime` in interface `GroupChannelMBean`
      Returns:
        long

    - #### getName

          public String getName()

      Description copied from interface: `Channel`
      Return the name of this channel.
      Specified by:
        `getName` in interface `Channel`
      Returns:
        channel name

    - #### setName

          public void setName(String name)

      Description copied from interface: `Channel`
      Set the name of this channel
      Specified by:
        `setName` in interface `Channel`
      Parameters:
        `name` - The new channel name

    - #### isJmxEnabled

          public boolean isJmxEnabled()

      Description copied from interface: `JmxChannel`
      If set to true, this channel is registered with jmx.
      Specified by:
        `isJmxEnabled` in interface `JmxChannel`
      Returns:
        true if this channel will be registered with jmx.

    - #### setJmxEnabled

          public void setJmxEnabled(boolean jmxEnabled)

      Description copied from interface: `JmxChannel`
      If set to true, this channel is registered with jmx.
      Specified by:
        `setJmxEnabled` in interface `JmxChannel`
      Parameters:
        `jmxEnabled` - set to true if this channel should be registered with jmx.

    - #### getJmxDomain

          public String getJmxDomain()

      Description copied from interface: `JmxChannel`
      Return the jmx domain which this channel is registered.
      Specified by:
        `getJmxDomain` in interface `JmxChannel`
      Returns:
        jmxDomain

    - #### setJmxDomain

          public void setJmxDomain(String jmxDomain)

      Description copied from interface: `JmxChannel`
      Set the jmx domain which this channel should be registered.
      Specified by:
        `setJmxDomain` in interface `JmxChannel`
      Parameters:
        `jmxDomain` - The jmx domain which this channel should be registered.

    - #### getJmxPrefix

          public String getJmxPrefix()

      Description copied from interface: `JmxChannel`
      Return the jmx prefix which will be used with channel ObjectName.
      Specified by:
        `getJmxPrefix` in interface `JmxChannel`
      Returns:
        jmxPrefix

    - #### setJmxPrefix

          public void setJmxPrefix(String jmxPrefix)

      Description copied from interface: `JmxChannel`
      Set the jmx prefix which will be used with channel ObjectName.
      Specified by:
        `setJmxPrefix` in interface `JmxChannel`
      Parameters:
        `jmxPrefix` - The jmx prefix which will be used with channel ObjectName.

    - #### preRegister

          public ObjectName preRegister(MBeanServer server,
                               ObjectName name)
                                 throws Exception

      Specified by:
        `preRegister` in interface `MBeanRegistration`
      Throws:
        `Exception`

    - #### postRegister

          public void postRegister(Boolean registrationDone)

      Specified by:
        `postRegister` in interface `MBeanRegistration`

    - #### preDeregister

          public void preDeregister()
                             throws Exception

      Specified by:
        `preDeregister` in interface `MBeanRegistration`
      Throws:
        `Exception`

    - #### postDeregister

          public void postDeregister()

      Specified by:
        `postDeregister` in interface `MBeanRegistration`

Copyright © 2000-2021 Apache Software Foundation. All Rights Reserved.