Package org.apache.catalina.tribes

Interface Channel

All Known Subinterfaces:

ManagedChannel

All Known Implementing Classes:

GroupChannel

public interface Channel

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:

• send messages
• receive message (by registering a ChannelListener
• get all members of the group getMembers()
• receive notifications of members added and members disappeared by registering a MembershipListener

The channel has 5 major components:

• Data receiver, with a built in thread pool to receive messages from other peers
• Data sender, an implementation for sending data using NIO or java.io
• Membership listener,listens for membership broadcasts
• Membership broadcaster, broadcasts membership pings.
• Channel interceptors, the ability to manipulate messages as they are sent or arrive

The channel layout is:

 
  ChannelListener_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]
 
 

See Also:

• example usage

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT	Start and stop sequences can be controlled by these constants.
static final int	MBR_RX_SEQ	Start and stop sequences can be controlled by these constants.
static final int	MBR_TX_SEQ	Start and stop sequences can be controlled by these constants.
static final int	SEND_OPTIONS_ASYNCHRONOUS	Send options, when a message is sent, it can have an option flag to trigger certain behavior.
static final int	SEND_OPTIONS_BYTE_MESSAGE	Send options, when a message is sent, it can have an option flag to trigger certain behavior.
static final int	SEND_OPTIONS_DEFAULT	Send options, when a message is sent, it can have an option flag to trigger certain behavior.
static final int	SEND_OPTIONS_MULTICAST	Send options.
static final int	SEND_OPTIONS_SECURE	Send options, when a message is sent, it can have an option flag to trigger certain behavior.
static final int	SEND_OPTIONS_SYNCHRONIZED_ACK	Send options, when a message is sent, it can have an option flag to trigger certain behavior.
static final int	SEND_OPTIONS_UDP	Send options.
static final int	SEND_OPTIONS_USE_ACK	Send options, when a message is sent, it can have an option flag to trigger certain behavior.
static final int	SND_RX_SEQ	Start and stop sequences can be controlled by these constants.
static final int	SND_TX_SEQ	Start and stop sequences can be controlled by these constants.

Method Summary

Modifier and Type	Method	Description
void	addChannelListener(ChannelListener listener)	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 listener)	Add a membership listener, will get notified when a new member joins, leaves or crashes.
Member	getLocalMember(boolean incAlive)	Return the member that represents this node.
Member	getMember(Member mbr)	Returns the member from the membership service with complete and recent data.
Member[]	getMembers()	Get all current group members.
String	getName()	Return the name of this channel.
static String	getSendOptionsAsString(int input)	Translates an integer value of SendOptions to its human-friendly comma separated value list for use in JMX and such.
static int	getSendOptionValue(String opt)	Translates the name of an option to its integer value.
ScheduledExecutorService	getUtilityExecutor()	Return executor that can be used for utility tasks.
boolean	hasMembers()	Returns true if there are any members in the group.
void	heartbeat()	Sends a heart beat through the interceptor stacks.
static int	parseSendOptions(String input)	Translates a comma separated list of option names to their bitwise-ORd value
void	removeChannelListener(ChannelListener listener)	Remove a channel listener, listeners are removed based on Object.hashCode() and Object.equals(Object).
void	removeMembershipListener(MembershipListener listener)	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
void	setHeartbeat(boolean enable)	Enables or disables internal heartbeat.
void	setName(String name)	Set the name of this channel
void	setUtilityExecutor(ScheduledExecutorService utilityExecutor)	Set the executor that can be used for utility tasks.
void	start(int svc)	Starts up the channel.
void	stop(int svc)	Shuts down the channel.

Field Details

DEFAULT

static 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_SEQ

static 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_SEQ

static 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_SEQ

static 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_SEQ

static 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_MESSAGE

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

See Also:

• send(Member[], Serializable, int)
• send(Member[], Serializable, int, ErrorHandler)
• Constant Field Values

SEND_OPTIONS_USE_ACK

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

See Also:

• send(Member[], Serializable, int)
• send(Member[], Serializable, int, ErrorHandler)
• Constant Field Values

SEND_OPTIONS_SYNCHRONIZED_ACK

static 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

See Also:

• send(Member[], Serializable, int)
• send(Member[], Serializable, int, ErrorHandler)
• Constant Field Values

SEND_OPTIONS_ASYNCHRONOUS

static 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 on MessageDispatchInterceptor.isAlwaysSend()

See Also:

• send(Member[], Serializable, int)
• send(Member[], Serializable, int, ErrorHandler)
• Constant Field Values

SEND_OPTIONS_SECURE

static 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

See Also:

• send(Member[], Serializable, int)
• send(Member[], Serializable, int, ErrorHandler)
• Constant Field Values

SEND_OPTIONS_UDP

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

See Also:

• send(Member[], Serializable, int)
• send(Member[], Serializable, int, ErrorHandler)
• Constant Field Values

SEND_OPTIONS_MULTICAST

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

See Also:

• send(Member[], Serializable, int)
• send(Member[], Serializable, int, ErrorHandler)
• Constant Field Values

SEND_OPTIONS_DEFAULT

static 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 is SEND_OPTIONS_USE_ACK

See Also:

• SEND_OPTIONS_USE_ACK
• send(Member[], Serializable, int)
• send(Member[], Serializable, int, ErrorHandler)
• Constant Field Values

Method Details

addInterceptor

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

Parameters:

interceptor - ChannelInterceptorBase

start

void start(int svc)
    throws ChannelException

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.

Parameters:

svc - one 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.

stop

void 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 - one 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.

send

UniqueId send(Member[] destination,
 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 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
• SEND_OPTIONS_USE_ACK
• SEND_OPTIONS_ASYNCHRONOUS
• SEND_OPTIONS_SYNCHRONIZED_ACK

send

UniqueId send(Member[] destination,
 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.

heartbeat

void 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)

setHeartbeat

void setHeartbeat(boolean enable)

Enables or disables internal heartbeat.

Parameters:

enable - boolean - default value is implementation specific

See Also:

• heartbeat()

addMembershipListener

void 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 the heartbeat() method will be invoked when the heartbeat runs on the channel

Parameters:

listener - MembershipListener

See Also:

• MembershipListener

addChannelListener

void addChannelListener(ChannelListener listener)

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

Parameters:

listener - ChannelListener

See Also:

• ChannelListener
• Heartbeat

removeMembershipListener

void removeMembershipListener(MembershipListener listener)

Remove a membership listener, listeners are removed based on Object.hashCode() and Object.equals(Object).

Parameters:

listener - MembershipListener

See Also:

• MembershipListener

removeChannelListener

void removeChannelListener(ChannelListener listener)

Remove a channel listener, listeners are removed based on Object.hashCode() and Object.equals(Object).

Parameters:

listener - ChannelListener

See Also:

• ChannelListener

hasMembers

boolean hasMembers()

Returns true if there are any members in the group. This call is the same as getMembers().length > 0

Returns:

boolean - true if there are any members automatically discovered

getMembers

Member[] getMembers()

Get all current group members.

Returns:

all members or empty array, never null

getLocalMember

Member 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

getMember

Member 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

getName

String getName()

Return the name of this channel.

Returns:

channel name

setName

void setName(String name)

Set the name of this channel

Parameters:

name - The new channel name

getUtilityExecutor

ScheduledExecutorService getUtilityExecutor()

Return executor that can be used for utility tasks.

Returns:

the executor

setUtilityExecutor

void setUtilityExecutor(ScheduledExecutorService utilityExecutor)

Set the executor that can be used for utility tasks.

Parameters:

utilityExecutor - the executor

getSendOptionValue

static int getSendOptionValue(String opt)

Translates the name of an option to its integer value. Valid option names are "asynchronous" (alias "async"), "byte_message" (alias "byte"), "multicast", "secure", "synchronized_ack" (alias "sync"), "udp", "use_ack"

Parameters:

opt - The name of the option

Returns:

the int value of the passed option name

parseSendOptions

static int parseSendOptions(String input)

Translates a comma separated list of option names to their bitwise-ORd value

Parameters:

input - A comma separated list of options, e.g. "async, multicast"

Returns:

a bitwise ORd value of the passed option names

getSendOptionsAsString

static String getSendOptionsAsString(int input)

Translates an integer value of SendOptions to its human-friendly comma separated value list for use in JMX and such.

Parameters:

input - the int value of SendOptions

Returns:

the human-friendly string representation in a reverse order (i.e. the last option will be shown first)