| org.apache.catalina.tribes.Channel
| Channel | | public interface Channel (Code) | | Channel 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 a ChannelListener
3. get all members of the group getMembers()
4. receive notifications of members added and members disappeared by
registerering a MembershipListener
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:
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]
For example usage @see org.apache.catalina.tribes.group.GroupChannel
author:
Filip Hanik
version:
$Revision: 467222 $, $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $ |
| Field Summary | |
| final public static int | DEFAULT
| | final public static 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. | | final public static 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. | | final public static int | SEND_OPTIONS_ASYNCHRONOUS
Send options, when a message is sent, it can have an option flag
to trigger certain behavior. | | final public static int | SEND_OPTIONS_BYTE_MESSAGE
Send options, when a message is sent, it can have an option flag
to trigger certain behavior. | | final public static int | SEND_OPTIONS_DEFAULT
Send options, when a message is sent, it can have an option flag
to trigger certain behavior. | | final public static int | SEND_OPTIONS_SECURE
Send options, when a message is sent, it can have an option flag
to trigger certain behavior. | | final public static int | SEND_OPTIONS_SYNCHRONIZED_ACK
Send options, when a message is sent, it can have an option flag
to trigger certain behavior. | | final public static int | SEND_OPTIONS_USE_ACK
Send options, when a message is sent, it can have an option flag
to trigger certain behavior. | | final public static 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. | | final public static 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. |
| DEFAULT | | final public static int DEFAULT(Code) | | 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: Channel.start(int)
See Also: Channel.stop(int) |
| MBR_RX_SEQ | | final public static int MBR_RX_SEQ(Code) | | 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: Channel.start(int)
See Also: Channel.stop(int) |
| MBR_TX_SEQ | | final public static int MBR_TX_SEQ(Code) | | 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: Channel.start(int)
See Also: Channel.stop(int) |
| SEND_OPTIONS_ASYNCHRONOUS | | final public static int SEND_OPTIONS_ASYNCHRONOUS(Code) | | 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
See Also: Channel.send(Member[],Serializable,int)
See Also: Channel.send(Member[],Serializable,int,ErrorHandler) |
| SEND_OPTIONS_BYTE_MESSAGE | | final public static int SEND_OPTIONS_BYTE_MESSAGE(Code) | | 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.
See Also: Channel.send(Member[],Serializable,int)
See Also: Channel.send(Member[],Serializable,int,ErrorHandler) |
| SEND_OPTIONS_DEFAULT | | final public static int SEND_OPTIONS_DEFAULT(Code) | | 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;
See Also: Channel.SEND_OPTIONS_USE_ACK
See Also: Channel.send(Member[],Serializable,int)
See Also: Channel.send(Member[],Serializable,int,ErrorHandler) |
| SEND_OPTIONS_SECURE | | final public static int SEND_OPTIONS_SECURE(Code) | | 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: Channel.send(Member[],Serializable,int)
See Also: Channel.send(Member[],Serializable,int,ErrorHandler) |
| SEND_OPTIONS_SYNCHRONIZED_ACK | | final public static int SEND_OPTIONS_SYNCHRONIZED_ACK(Code) | | 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: Channel.send(Member[],Serializable,int)
See Also: Channel.send(Member[],Serializable,int,ErrorHandler) |
| SEND_OPTIONS_USE_ACK | | final public static int SEND_OPTIONS_USE_ACK(Code) | | 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: Channel.send(Member[],Serializable,int)
See Also: Channel.send(Member[],Serializable,int,ErrorHandler) |
| SND_RX_SEQ | | final public static int SND_RX_SEQ(Code) | | 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: Channel.start(int)
See Also: Channel.stop(int) |
| SND_TX_SEQ | | final public static int SND_TX_SEQ(Code) | | 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: Channel.start(int)
See Also: Channel.stop(int) |
| addChannelListener | | public void addChannelListener(ChannelListener listener)(Code) | | 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
See Also: Heartbeat |
| addInterceptor | | public void addInterceptor(ChannelInterceptor interceptor)(Code) | | Adds an interceptor to the channel message chain.
Parameters:
interceptor - ChannelInterceptor |
| addMembershipListener | | public void addMembershipListener(MembershipListener listener)(Code) | | 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 |
| getLocalMember | | public Member getLocalMember(boolean incAlive)(Code) | | 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 timesince the membership service started. Member |
| getMember | | public Member getMember(Member mbr)(Code) | | 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 Member |
| getMembers | | public Member[] getMembers()(Code) | | Get all current group members
all members or empty array, never null |
| hasMembers | | public boolean hasMembers()(Code) | | Returns true if there are any members in the group,
this call is the same as getMembers().length>0
boolean - true if there are any members automatically discovered |
| heartbeat | | public void heartbeat()(Code) | | 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: Channel.setHeartbeat(boolean) |
| removeChannelListener | | public void removeChannelListener(ChannelListener listener)(Code) | | remove a channel listener, listeners are removed based on Object.hashCode and Object.equals
Parameters:
listener - ChannelListener
See Also: ChannelListener |
| removeMembershipListener | | public void removeMembershipListener(MembershipListener listener)(Code) | | remove a membership listener, listeners are removed based on Object.hashCode and Object.equals
Parameters:
listener - MembershipListener
See Also: MembershipListener |
| send | | public UniqueId send(Member[] destination, Serializable msg, int options) throws ChannelException(Code) | | Send a message to one or more members in the cluster
Parameters:
destination - Member[] - the destinations, can not be null or zero length, the reason for thatis that a membership change can occur and at that time the application is uncertain what group the messageactually got sent to.
Parameters:
msg - Serializable - the message to send, has to be serializable, or a ByteMessage to send a pure byte array
Parameters:
options - int - sender options, see class documentation for each interceptor that is configured in order to trigger interceptors a unique Id that identifies the message that is sent
See Also: ByteMessage
See Also: Channel.SEND_OPTIONS_USE_ACK
See Also: Channel.SEND_OPTIONS_ASYNCHRONOUS
See Also: Channel.SEND_OPTIONS_SYNCHRONIZED_ACK |
| send | | public UniqueId send(Member[] destination, Serializable msg, int options, ErrorHandler handler) throws ChannelException(Code) | | Send a message to one or more members in the cluster
Parameters:
destination - Member[] - the destinations, null or zero length means all
Parameters:
msg - ClusterMessage - the message to send
Parameters:
options - int - sender options, see class documentation
Parameters:
handler - ErrorHandler - handle errors through a callback, rather than throw it a unique Id that identifies the message that is sent
exception:
ChannelException - - if a serialization error happens. |
| setHeartbeat | | public void setHeartbeat(boolean enable)(Code) | | Enables or disables internal heartbeat.
Parameters:
enable - boolean - default value is implementation specific
See Also: Channel.heartbeat() |
| start | | public void start(int svc) throws ChannelException(Code) | | 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 - 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. |
| stop | | public void stop(int svc) throws ChannelException(Code) | | 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. |
|
|