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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	GroupChannel.HeartbeatRunnable	Title: Internal heartbeat runnable
static class	GroupChannel.InterceptorIterator	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	Description
protected final List<ChannelListener>	channelListeners	A list of channel listeners that subscribe to incoming messages
protected final ChannelCoordinator	coordinator	The ChannelCoordinator coordinates the bottom layer components: - MembershipService - ChannelSender - ChannelReceiver
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 ScheduledFuture<?>	heartbeatFuture	Internal heartbeat future
protected long	heartbeatSleeptime	If heartbeat == true then how often do we want this heartbeat to run.
protected ChannelInterceptor	interceptors	The first interceptor in the interceptor stack.
protected final List<MembershipListener>	membershipListeners	A list of membership listeners that subscribe to membership announcements
protected ScheduledFuture<?>	monitorFuture
protected String	name	the name of this channel.
protected boolean	optionCheck	If set to true, the GroupChannel will check to make sure that
protected boolean	ownExecutor
protected static final StringManager	sm
protected ScheduledExecutorService	utilityExecutor	Executor service.

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	Description
GroupChannel()	Creates a GroupChannel.

Method Summary

Modifier and Type	Method	Description
void	addChannelListener(ChannelListener channelListener)	Add a channel listener, this is a callback object when messages are received.
void	addInterceptor(ChannelInterceptor interceptor)	Adds an interceptor to the stack for message processing.
void	addMembershipListener(MembershipListener membershipListener)	Add a membership listener, will get notified when a new member joins, leaves or crashes.
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
ChannelSender	getChannelSender()	returns the channel sender
ChannelInterceptor	getFirstInterceptor()	Returns the first interceptor of the stack.
boolean	getHeartbeat()
long	getHeartbeatSleeptime()
Iterator<ChannelInterceptor>	getInterceptors()	Returns the interceptor 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
String	getName()	Return the name of this channel.
boolean	getOptionCheck()
ScheduledExecutorService	getUtilityExecutor()	Return executor that can be used for utility tasks.
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)
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)	Remove a channel listener, listeners are removed based on Object.hashCode() and Object.equals(Object).
void	removeMembershipListener(MembershipListener membershipListener)	Remove a membership listener, listeners are removed based on Object.hashCode() and Object.equals(Object).
UniqueId	send(Member[] destination, Serializable msg, int options)	Send a message to one or more members in the cluster
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 an RPC message comes in and no channel listener accepts the message.
void	setChannelReceiver(ChannelReceiver clusterReceiver)	Sets the channel receiver
void	setChannelSender(ChannelSender clusterSender)	Sets the channel sender
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
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 service
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	setUtilityExecutor(ScheduledExecutorService utilityExecutor)	Set the executor that can be used for utility tasks.
void	start(int svc)	Starts up the channel.
protected void	startHeartbeat()
void	stop(int svc)	Shuts down 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 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:

• Channel.setHeartbeat(boolean)

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:

• ByteMessage
• Channel.SEND_OPTIONS_USE_ACK
• Channel.SEND_OPTIONS_ASYNCHRONOUS
• Channel.SEND_OPTIONS_SYNCHRONIZED_ACK

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:

• 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

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:

• Channel

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:

• Channel

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:

• ChannelReceiver

getChannelSender

public ChannelSender getChannelSender()

Description copied from interface: ManagedChannel

returns the channel sender

Specified by:

getChannelSender in interface ManagedChannel

Returns:

ChannelSender

See Also:

• ChannelSender

getMembershipService

public MembershipService getMembershipService()

Description copied from interface: ManagedChannel

Returns the membership service

Specified by:

getMembershipService in interface ManagedChannel

Returns:

MembershipService

See Also:

• MembershipService

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:

• ChannelReceiver

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:

• ChannelSender

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:

• MembershipService

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:

• MembershipListener

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:

• MembershipListener

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:

• ChannelListener
• Heartbeat

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:

• ChannelListener

getInterceptors

public Iterator<ChannelInterceptor> getInterceptors()

Description copied from interface: ManagedChannel

Returns the interceptor 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

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