Package 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.

  • Field Details

    • 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. The default value is 5000 milliseconds.

    • heartbeatFuture

      protected ScheduledFuture<?> heartbeatFuture
      Internal heartbeat future

    • monitorFuture

      protected ScheduledFuture<?> monitorFuture

    • 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.

    • utilityExecutor

      protected ScheduledExecutorService utilityExecutor
      Executor service.

    • ownExecutor

      protected boolean ownExecutor

  • Constructor Details

    • 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 Details

    • addInterceptor

      public void addInterceptor(ChannelInterceptor interceptor)
      Description copied from interface: Channel
      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:

    • send

      public UniqueId send(Member[] destination, Serializable msg, int options) 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[] - the destinations, cannot be null or zero length, the reason for that is that a membership change can occur and at that time the application is uncertain what group the message actually got sent to.
      msg - Serializable - the message to send, has to be serializable, or a ByteMessage to send a pure byte array
      options - int - sender options, see class documentation for each interceptor that is configured in order to trigger interceptors
      Returns:
      a unique Id that identifies the message that is sent
      Throws:
      ChannelException - if a serialization error happens.
      See Also:

    • 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[] - the destinations, null or zero length means all
      msg - ClusterMessage - the message to send
      options - int - sender options, see class documentation
      handler - ErrorHandler - handle errors through a callback, rather than throw it
      Returns:
      a unique Id that identifies the message that is sent
      Throws:
      ChannelException - - if a serialization error happens.

    • 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 an 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:

    • 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
      Description copied from interface: ChannelInterceptor
      Starts up the channel. This can be called multiple times for individual services to start The svc parameter can be the logical or value of any constants
      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 - one of:
      • Channel.DEFAULT - will start all services
      • Channel.MBR_RX_SEQ - starts the membership receiver
      • Channel.MBR_TX_SEQ - starts the membership broadcaster
      • Channel.SND_TX_SEQ - starts the replication transmitter
      • Channel.SND_RX_SEQ - starts the replication receiver
      Throws:
      ChannelException - if a startup error occurs or the service is already started.
      See Also:

    • startHeartbeat

      protected void startHeartbeat()

    • stop

      public void stop(int svc) throws ChannelException
      Description copied from interface: ChannelInterceptor
      Shuts down the channel. This can be called multiple times for individual services to shutdown The svc parameter can be the logical or value of any constants
      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 - one of:
      • Channel.DEFAULT - will shutdown all services
      • Channel.MBR_RX_SEQ - stops the membership receiver
      • Channel.MBR_TX_SEQ - stops the membership broadcaster
      • Channel.SND_TX_SEQ - stops the replication transmitter
      • Channel.SND_RX_SEQ - stops the replication receiver
      Throws:
      ChannelException - if a startup error occurs or the service is already started.
      See Also:

    • getFirstInterceptor

      public ChannelInterceptor getFirstInterceptor()
      Returns the first interceptor of the stack. Useful for traversal.
      Returns:
      ChannelInterceptor

    • getUtilityExecutor

      public ScheduledExecutorService getUtilityExecutor()
      Description copied from interface: Channel
      Return executor that can be used for utility tasks.
      Specified by:
      getUtilityExecutor in interface Channel
      Returns:
      the executor

    • setUtilityExecutor

      public void setUtilityExecutor(ScheduledExecutorService utilityExecutor)
      Description copied from interface: Channel
      Set the executor that can be used for utility tasks.
      Specified by:
      setUtilityExecutor in interface Channel
      Parameters:
      utilityExecutor - the executor

    • getChannelReceiver

      public ChannelReceiver getChannelReceiver()
      Description copied from interface: ManagedChannel
      returns the channel receiver
      Specified by:
      getChannelReceiver in interface ManagedChannel
      Returns:
      ChannelReceiver
      See Also:

    • getChannelSender

      public ChannelSender getChannelSender()
      Description copied from interface: ManagedChannel
      returns the channel sender
      Specified by:
      getChannelSender in interface ManagedChannel
      Returns:
      ChannelSender
      See Also:

    • getMembershipService

      public MembershipService getMembershipService()
      Description copied from interface: ManagedChannel
      Returns the membership service
      Specified by:
      getMembershipService in interface ManagedChannel
      Returns:
      MembershipService
      See Also:

    • setChannelReceiver

      public void setChannelReceiver(ChannelReceiver clusterReceiver)
      Description copied from interface: ManagedChannel
      Sets the channel receiver
      Specified by:
      setChannelReceiver in interface ManagedChannel
      Parameters:
      clusterReceiver - ChannelReceiver
      See Also:

    • setChannelSender

      public void setChannelSender(ChannelSender clusterSender)
      Description copied from interface: ManagedChannel
      Sets the channel sender
      Specified by:
      setChannelSender in interface ManagedChannel
      Parameters:
      clusterSender - ChannelSender
      See Also:

    • setMembershipService

      public void setMembershipService(MembershipService membershipService)
      Description copied from interface: ManagedChannel
      Sets the membership service
      Specified by:
      setMembershipService in interface ManagedChannel
      Parameters:
      membershipService - MembershipService
      See Also:

    • addMembershipListener

      public void addMembershipListener(MembershipListener membershipListener)
      Description copied from interface: Channel
      Add a membership listener, will get notified when a new member joins, leaves or crashes.

      If the membership listener implements the Heartbeat interface the heartbeat() method will be invoked when the heartbeat runs on the channel

      Specified by:
      addMembershipListener in interface Channel
      Specified by:
      addMembershipListener in interface GroupChannelMBean
      Parameters:
      membershipListener - MembershipListener
      See Also:

    • removeMembershipListener

      public void removeMembershipListener(MembershipListener membershipListener)
      Description copied from interface: Channel
      Remove a membership listener, listeners are removed based on Object.hashCode() and Object.equals(Object).
      Specified by:
      removeMembershipListener in interface Channel
      Specified by:
      removeMembershipListener in interface GroupChannelMBean
      Parameters:
      membershipListener - MembershipListener
      See Also:

    • addChannelListener

      public void addChannelListener(ChannelListener channelListener)
      Description copied from interface: Channel
      Add a channel listener, this is a callback object when messages are received.

      If the channel listener implements the Heartbeat interface the heartbeat() method will be invoked when the heartbeat runs on the channel

      Specified by:
      addChannelListener in interface Channel
      Specified by:
      addChannelListener in interface GroupChannelMBean
      Parameters:
      channelListener - ChannelListener
      See Also:

    • removeChannelListener

      public void removeChannelListener(ChannelListener channelListener)
      Description copied from interface: Channel
      Remove a channel listener, listeners are removed based on Object.hashCode() and Object.equals(Object).
      Specified by:
      removeChannelListener in interface Channel
      Specified by:
      removeChannelListener in interface GroupChannelMBean
      Parameters:
      channelListener - ChannelListener
      See Also:

    • getInterceptors

      public Iterator<ChannelInterceptor> getInterceptors()
      Description copied from interface: ManagedChannel
      Returns the interceptor stack
      Specified by:
      getInterceptors in interface ManagedChannel
      Returns:
      Iterator
      See Also:

    • 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:

    • getOptionCheck

      public boolean getOptionCheck()
      Specified by:
      getOptionCheck in interface GroupChannelMBean

    • getHeartbeat

      public boolean getHeartbeat()
      Specified by:
      getHeartbeat in interface GroupChannelMBean

    • getHeartbeatSleeptime

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

    • 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