Package org.apache.catalina.tribes
Interface Channel
- 
- All Known Subinterfaces:
- ManagedChannel
 - All Known Implementing Classes:
- GroupChannel
 
 public interface ChannelChannel interface
 A channel is a representation of a group of nodes all participating in some sort of communication with each other.
 The channel is the main API class for Tribes, this is essentially the only class that an application needs to be aware of. Through the channel the application can:
 1. send messages
 2. receive message (by registering aChannelListener
 3. get all members of the groupgetMembers()
 4. receive notifications of members added and members disappeared by registering aMembershipListener
 
 The channel has 5 major components:
 1. Data receiver, with a built in thread pool to receive messages from other peers
 2. Data sender, an implementation for sending data using NIO or java.io
 3. Membership listener,listens for membership broadcasts
 4. Membership broadcaster, broadcasts membership pings.
 5. Channel interceptors, the ability to manipulate messages as they are sent or arrive
 The channel layout is:
 For example usage @see org.apache.catalina.tribes.group.GroupChannelChannelListener_1..ChannelListener_N MembershipListener_1..MembershipListener_N [Application Layer] \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / \ \ / / --------------------------------------- | | Channel | ChannelInterceptor_1 | [Channel stack] ChannelInterceptor_N | Coordinator (implements MessageListener,MembershipListener,ChannelInterceptor) -------------------- / | \ / | \ / | \ / | \ / | \ MembershipService ChannelSender ChannelReceiver [IO layer]
- 
- 
Field SummaryFields Modifier and Type Field Description static intDEFAULTStart and stop sequences can be controlled by these constants This allows you to start separate components of the channel
 DEFAULT - starts or stops all components in the channelstatic intMBR_RX_SEQStart and stop sequences can be controlled by these constants This allows you to start separate components of the channel
 MBR_RX_SEQ - starts or stops the membership listener.static intMBR_TX_SEQStart and stop sequences can be controlled by these constants This allows you to start separate components of the channel
 MBR_TX_SEQ - starts or stops the membership broadcaster.static intSEND_OPTIONS_ASYNCHRONOUSSend options, when a message is sent, it can have an option flag to trigger certain behavior.static intSEND_OPTIONS_BYTE_MESSAGESend options, when a message is sent, it can have an option flag to trigger certain behavior.static intSEND_OPTIONS_DEFAULTSend options, when a message is sent, it can have an option flag to trigger certain behavior.static intSEND_OPTIONS_MULTICASTSend options.static intSEND_OPTIONS_SECURESend options, when a message is sent, it can have an option flag to trigger certain behavior.static intSEND_OPTIONS_SYNCHRONIZED_ACKSend options, when a message is sent, it can have an option flag to trigger certain behavior.static intSEND_OPTIONS_UDPSend options.static intSEND_OPTIONS_USE_ACKSend options, when a message is sent, it can have an option flag to trigger certain behavior.static intSND_RX_SEQStart and stop sequences can be controlled by these constants This allows you to start separate components of the channel
 SND_RX_SEQ - starts or stops the data receiver.static intSND_TX_SEQStart and stop sequences can be controlled by these constants This allows you to start separate components of the channel
 SND_TX_SEQ - starts or stops the data sender.
 - 
Method SummaryAll Methods Instance Methods Abstract Methods Modifier and Type Method Description voidaddChannelListener(ChannelListener listener)Add a channel listener, this is a callback object when messages are received
 If the channel listener implements the Heartbeat interface theheartbeat()method will be invoked when the heartbeat runs on the channelvoidaddInterceptor(ChannelInterceptor interceptor)Adds an interceptor to the channel message chain.voidaddMembershipListener(MembershipListener listener)Add a membership listener, will get notified when a new member joins, leaves or crashes
 If the membership listener implements the Heartbeat interface theheartbeat()method will be invoked when the heartbeat runs on the channelMembergetLocalMember(boolean incAlive)Return the member that represents this node.MembergetMember(Member mbr)Returns the member from the membership service with complete and recent data.Member[]getMembers()Get all current group membersjava.lang.StringgetName()Return the name of this channel.booleanhasMembers()Returns true if there are any members in the group, this call is the same asgetMembers().length > 0voidheartbeat()Sends a heart beat through the interceptor stacks Use this method to alert interceptors and other components to clean up garbage, timed out messages etc.
 If you application has a background thread, then you can save one thread, by configuring your channel to not use an internal heartbeat thread and invoking this method.voidremoveChannelListener(ChannelListener listener)remove a channel listener, listeners are removed based on Object.hashCode and Object.equalsvoidremoveMembershipListener(MembershipListener listener)remove a membership listener, listeners are removed based on Object.hashCode and Object.equalsUniqueIdsend(Member[] destination, java.io.Serializable msg, int options)Send a message to one or more members in the clusterUniqueIdsend(Member[] destination, java.io.Serializable msg, int options, ErrorHandler handler)Send a message to one or more members in the clustervoidsetHeartbeat(boolean enable)Enables or disables internal heartbeat.voidsetName(java.lang.String name)Set the name of this channelvoidstart(int svc)Starts up the channel.voidstop(int svc)Shuts down the channel.
 
- 
- 
- 
Field Detail- 
DEFAULTstatic final int DEFAULT Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
 DEFAULT - starts or stops all components in the channel- See Also:
- start(int),- stop(int), Constant Field Values
 
 - 
SND_RX_SEQstatic final int SND_RX_SEQ Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
 SND_RX_SEQ - starts or stops the data receiver. Start means opening a server socket in case of a TCP implementation- See Also:
- start(int),- stop(int), Constant Field Values
 
 - 
SND_TX_SEQstatic final int SND_TX_SEQ Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
 SND_TX_SEQ - starts or stops the data sender. This should not open any sockets, as sockets are opened on demand when a message is being sent- See Also:
- start(int),- stop(int), Constant Field Values
 
 - 
MBR_RX_SEQstatic final int MBR_RX_SEQ Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
 MBR_RX_SEQ - starts or stops the membership listener. In a multicast implementation this will open a datagram socket and join a group and listen for membership messages members joining- See Also:
- start(int),- stop(int), Constant Field Values
 
 - 
MBR_TX_SEQstatic final int MBR_TX_SEQ Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
 MBR_TX_SEQ - starts or stops the membership broadcaster. In a multicast implementation this will open a datagram socket and join a group and broadcast the local member information- See Also:
- start(int),- stop(int), Constant Field Values
 
 - 
SEND_OPTIONS_BYTE_MESSAGEstatic final int SEND_OPTIONS_BYTE_MESSAGE Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
 However, there are five default flags that every channel implementation must implement
 SEND_OPTIONS_BYTE_MESSAGE - The message is a pure byte message and no marshaling or unmarshaling will be performed.
 - 
SEND_OPTIONS_USE_ACKstatic final int SEND_OPTIONS_USE_ACK Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
 However, there are five default flags that every channel implementation must implement
 SEND_OPTIONS_USE_ACK - Message is sent and an ACK is received when the message has been received by the recipient
 If no ack is received, the message is not considered successful
 - 
SEND_OPTIONS_SYNCHRONIZED_ACKstatic final int SEND_OPTIONS_SYNCHRONIZED_ACK Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
 However, there are five default flags that every channel implementation must implement
 SEND_OPTIONS_SYNCHRONIZED_ACK - Message is sent and an ACK is received when the message has been received and processed by the recipient
 If no ack is received, the message is not considered successful
 - 
SEND_OPTIONS_ASYNCHRONOUSstatic final int SEND_OPTIONS_ASYNCHRONOUS Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
 However, there are five default flags that every channel implementation must implement
 SEND_OPTIONS_ASYNCHRONOUS - Message will be placed on a queue and sent by a separate thread
 If the queue is full, behaviour depends onMessageDispatchInterceptor.isAlwaysSend()
 - 
SEND_OPTIONS_SECUREstatic final int SEND_OPTIONS_SECURE Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
 However, there are five default flags that every channel implementation must implement
 SEND_OPTIONS_SECURE - Message is sent over an encrypted channel
 - 
SEND_OPTIONS_UDPstatic final int SEND_OPTIONS_UDP Send options. When a message is sent with this flag on the system sends the message using UDP instead of TCP
 - 
SEND_OPTIONS_MULTICASTstatic final int SEND_OPTIONS_MULTICAST Send options. When a message is sent with this flag on the system sends a UDP message on the Multicast address instead of UDP or TCP to individual addresses
 - 
SEND_OPTIONS_DEFAULTstatic final int SEND_OPTIONS_DEFAULT Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
 However, there are five default flags that every channel implementation must implement
 SEND_OPTIONS_DEFAULT - the default sending options, just a helper variable.
 The default isint SEND_OPTIONS_DEFAULT = SEND_OPTIONS_USE_ACK;
 
- 
 - 
Method Detail- 
addInterceptorvoid addInterceptor(ChannelInterceptor interceptor) Adds an interceptor to the channel message chain.- Parameters:
- interceptor- ChannelInterceptor
 
 - 
startvoid start(int svc) throws ChannelExceptionStarts 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- Parameters:
- svc- int value of
 DEFAULT - will start all services
 MBR_RX_SEQ - starts the membership receiver
 MBR_TX_SEQ - starts the membership broadcaster
 SND_TX_SEQ - starts the replication transmitter
 SND_RX_SEQ - starts the replication receiver
 Note: In order for the membership broadcaster to transmit the correct information, it has to be started after the replication receiver.
- Throws:
- ChannelException- if a startup error occurs or the service is already started or an error occurs.
 
 - 
stopvoid stop(int svc) throws ChannelException 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- Parameters:
- svc- int value of
 DEFAULT - will shutdown all services
 MBR_RX_SEQ - stops the membership receiver
 MBR_TX_SEQ - stops the membership broadcaster
 SND_TX_SEQ - stops the replication transmitter
 SND_RX_SEQ - stops the replication receiver
- Throws:
- ChannelException- if a startup error occurs or the service is already stopped or an error occurs.
 
 - 
sendUniqueId send(Member[] destination, java.io.Serializable msg, int options) throws ChannelException Send a message to one or more members in the cluster- 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- ByteMessageto 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,- SEND_OPTIONS_USE_ACK,- SEND_OPTIONS_ASYNCHRONOUS,- SEND_OPTIONS_SYNCHRONIZED_ACK
 
 - 
sendUniqueId send(Member[] destination, java.io.Serializable msg, int options, ErrorHandler handler) throws ChannelException Send a message to one or more members in the cluster- 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.
 
 - 
heartbeatvoid heartbeat() Sends a heart beat through the interceptor stacks Use this method to alert interceptors and other components to clean up garbage, timed out messages etc.
 If you application has a background thread, then you can save one thread, by configuring your channel to not use an internal heartbeat thread and invoking this method.- See Also:
- setHeartbeat(boolean)
 
 - 
setHeartbeatvoid setHeartbeat(boolean enable) Enables or disables internal heartbeat.- Parameters:
- enable- boolean - default value is implementation specific
- See Also:
- heartbeat()
 
 - 
addMembershipListenervoid addMembershipListener(MembershipListener listener) Add a membership listener, will get notified when a new member joins, leaves or crashes
 If the membership listener implements the Heartbeat interface theheartbeat()method will be invoked when the heartbeat runs on the channel- Parameters:
- listener- MembershipListener
- See Also:
- MembershipListener
 
 - 
addChannelListenervoid addChannelListener(ChannelListener listener) Add a channel listener, this is a callback object when messages are received
 If the channel listener implements the Heartbeat interface theheartbeat()method will be invoked when the heartbeat runs on the channel- Parameters:
- listener- ChannelListener
- See Also:
- ChannelListener,- Heartbeat
 
 - 
removeMembershipListenervoid removeMembershipListener(MembershipListener listener) remove a membership listener, listeners are removed based on Object.hashCode and Object.equals- Parameters:
- listener- MembershipListener
- See Also:
- MembershipListener
 
 - 
removeChannelListenervoid removeChannelListener(ChannelListener listener) remove a channel listener, listeners are removed based on Object.hashCode and Object.equals- Parameters:
- listener- ChannelListener
- See Also:
- ChannelListener
 
 - 
hasMembersboolean hasMembers() Returns true if there are any members in the group, this call is the same asgetMembers().length > 0- Returns:
- boolean - true if there are any members automatically discovered
 
 - 
getMembersMember[] getMembers() Get all current group members- Returns:
- all members or empty array, never null
 
 - 
getLocalMemberMember getLocalMember(boolean incAlive) Return the member that represents this node. This is also the data that gets broadcasted through the membership broadcaster component- Parameters:
- incAlive- - optimization, true if you want it to calculate alive time since the membership service started.
- Returns:
- Member
 
 - 
getMemberMember getMember(Member mbr) Returns the member from the membership service with complete and recent data. Some implementations might serialize and send membership information along with a message, and instead of sending complete membership details, only send the primary identifier for the member but not the payload or other information. When such message is received the application can retrieve the cached member through this call.
 In most cases, this is not necessary.- Parameters:
- mbr- Member
- Returns:
- Member
 
 - 
getNamejava.lang.String getName() Return the name of this channel.- Returns:
- channel name
 
 - 
setNamevoid setName(java.lang.String name) Set the name of this channel- Parameters:
- name- The new channel name
 
 
- 
 
-