File	Doc	Category	Size	Date	Package
Channel.java	API Doc	Apache Tomcat 6.0.14	16831	Fri Jul 20 04:20:32 BST 2007	org.apache.catalina.tribes

Channel

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]

Fields Summary
public 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
public 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
public 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
public 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
public 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
public 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 marshalling or unmarshalling will be performed.
public 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
public 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
public 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 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
public 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
public 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 int SEND_OPTIONS_DEFAULT = SEND_OPTIONS_USE_ACK;

Constructors Summary

Methods Summary
public 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 param listener ChannelListener see ChannelListener see Heartbeat
public void	addInterceptor(ChannelInterceptor interceptor) Adds an interceptor to the channel message chain. param interceptor ChannelInterceptor
public 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 param listener MembershipListener see MembershipListener
public Member	getLocalMember(boolean incAlive) Return the member that represents this node. This is also the data that gets broadcasted through the membership broadcaster component param incAlive - optimization, true if you want it to calculate alive time since the membership service started. return Member
public 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. param mbr Member return Member
public Member[]	getMembers() Get all current group members return all members or empty array, never null
public boolean	hasMembers() Returns true if there are any members in the group, this call is the same as getMembers().length>0 return boolean - true if there are any members automatically discovered
public 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 #setHeartbeat(boolean)
public void	removeChannelListener(ChannelListener listener) remove a channel listener, listeners are removed based on Object.hashCode and Object.equals param listener ChannelListener see ChannelListener
public void	removeMembershipListener(MembershipListener listener) remove a membership listener, listeners are removed based on Object.hashCode and Object.equals param listener MembershipListener see MembershipListener
public UniqueId	send(Member[] destination, java.io.Serializable msg, int options) Send a message to one or more members in the cluster param destination Member[] - the destinations, can not 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. param msg Serializable - the message to send, has to be serializable, or a ByteMessage to send a pure byte array param options int - sender options, see class documentation for each interceptor that is configured in order to trigger interceptors return a unique Id that identifies the message that is sent see ByteMessage see #SEND_OPTIONS_USE_ACK see #SEND_OPTIONS_ASYNCHRONOUS see #SEND_OPTIONS_SYNCHRONIZED_ACK
public UniqueId	send(Member[] destination, java.io.Serializable msg, int options, ErrorHandler handler) Send a message to one or more members in the cluster param destination Member[] - the destinations, null or zero length means all param msg ClusterMessage - the message to send param options int - sender options, see class documentation param handler ErrorHandler - handle errors through a callback, rather than throw it return a unique Id that identifies the message that is sent exception ChannelException - if a serialization error happens.
public void	setHeartbeat(boolean enable) Enables or disables internal heartbeat. param enable boolean - default value is implementation specific see #heartbeat()
public void	start(int svc) 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 param 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.
public void	stop(int svc) 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 param 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.