Home » apache-tomcat-6.0.26-src » org.apache » catalina » tribes » [javadoc | source]
org.apache.catalina.tribes
public interface: Channel [javadoc | source]

All Known Implementing Classes:
    GroupChannel, ManagedChannel

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
Field 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;
 
Method from org.apache.catalina.tribes.Channel Summary:
addChannelListener,   addInterceptor,   addMembershipListener,   getLocalMember,   getMember,   getMembers,   hasMembers,   heartbeat,   removeChannelListener,   removeMembershipListener,   send,   send,   setHeartbeat,   start,   stop
Method from org.apache.catalina.tribes.Channel Detail:
 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
 public  void addInterceptor(ChannelInterceptor interceptor)
    Adds an interceptor to the channel message chain.
 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
 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
 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.
 public Member[] getMembers()
    Get all current group members
 public boolean hasMembers()
    Returns true if there are any members in the group, this call is the same as getMembers().length>0
 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.
 public  void removeChannelListener(ChannelListener listener)
    remove a channel listener, listeners are removed based on Object.hashCode and Object.equals
 public  void removeMembershipListener(MembershipListener listener)
    remove a membership listener, listeners are removed based on Object.hashCode and Object.equals
 public UniqueId send(Member[] destination,
    Serializable msg,
    int options) throws ChannelException
    Send a message to one or more members in the cluster
 public UniqueId send(Member[] destination,
    Serializable msg,
    int options,
    ErrorHandler handler) throws ChannelException
    Send a message to one or more members in the cluster
 public  void setHeartbeat(boolean enable)
    Enables or disables internal heartbeat.
 public  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
 public  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