373 lines
17 KiB
Java
373 lines
17 KiB
Java
/*
|
|
* Licensed to the Apache Software Foundation (ASF) under one or more
|
|
* contributor license agreements. See the NOTICE file distributed with
|
|
* this work for additional information regarding copyright ownership.
|
|
* The ASF licenses this file to You under the Apache License, Version 2.0
|
|
* (the "License"); you may not use this file except in compliance with
|
|
* the License. You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
package org.apache.catalina.tribes;
|
|
|
|
import java.io.Serializable;
|
|
|
|
/**
|
|
* Channel interface<br>
|
|
* A channel is a representation of a group of nodes all participating in some sort of
|
|
* communication with each other.<br>
|
|
* 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:<br>
|
|
* 1. send messages<br>
|
|
* 2. receive message (by registering a <code>ChannelListener</code><br>
|
|
* 3. get all members of the group <code>getMembers()</code><br>
|
|
* 4. receive notifications of members added and members disappeared by
|
|
* registering a <code>MembershipListener</code><br>
|
|
* <br>
|
|
* The channel has 5 major components:<br>
|
|
* 1. Data receiver, with a built in thread pool to receive messages from other peers<br>
|
|
* 2. Data sender, an implementation for sending data using NIO or java.io<br>
|
|
* 3. Membership listener,listens for membership broadcasts<br>
|
|
* 4. Membership broadcaster, broadcasts membership pings.<br>
|
|
* 5. Channel interceptors, the ability to manipulate messages as they are sent or arrive<br><br>
|
|
* The channel layout is:
|
|
* <pre><code>
|
|
* 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]
|
|
* </code></pre>
|
|
*
|
|
* For example usage @see org.apache.catalina.tribes.group.GroupChannel
|
|
*/
|
|
public interface Channel {
|
|
|
|
/**
|
|
* Start and stop sequences can be controlled by these constants
|
|
* This allows you to start separate components of the channel <br>
|
|
* DEFAULT - starts or stops all components in the channel
|
|
* @see #start(int)
|
|
* @see #stop(int)
|
|
*/
|
|
public static final int DEFAULT = 15;
|
|
|
|
/**
|
|
* Start and stop sequences can be controlled by these constants
|
|
* This allows you to start separate components of the channel <br>
|
|
* SND_RX_SEQ - starts or stops the data receiver. Start means opening a server socket
|
|
* in case of a TCP implementation
|
|
* @see #start(int)
|
|
* @see #stop(int)
|
|
*/
|
|
public static final int SND_RX_SEQ = 1;
|
|
|
|
/**
|
|
* Start and stop sequences can be controlled by these constants
|
|
* This allows you to start separate components of the channel <br>
|
|
* 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 #start(int)
|
|
* @see #stop(int)
|
|
*/
|
|
public static final int SND_TX_SEQ = 2;
|
|
|
|
/**
|
|
* Start and stop sequences can be controlled by these constants
|
|
* This allows you to start separate components of the channel <br>
|
|
* 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 #start(int)
|
|
* @see #stop(int)
|
|
*/
|
|
public static final int MBR_RX_SEQ = 4;
|
|
|
|
/**
|
|
* Start and stop sequences can be controlled by these constants
|
|
* This allows you to start separate components of the channel <br>
|
|
* 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 #start(int)
|
|
* @see #stop(int)
|
|
*/
|
|
public static final int MBR_TX_SEQ = 8;
|
|
|
|
/**
|
|
* 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. <br>
|
|
* However, there are five default flags that every channel implementation must implement<br>
|
|
* SEND_OPTIONS_BYTE_MESSAGE - The message is a pure byte message and no marshaling or unmarshaling will
|
|
* be performed.<br>
|
|
*
|
|
* @see #send(Member[], Serializable , int)
|
|
* @see #send(Member[], Serializable, int, ErrorHandler)
|
|
*/
|
|
public static final int SEND_OPTIONS_BYTE_MESSAGE = 0x0001;
|
|
|
|
/**
|
|
* 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. <br>
|
|
* However, there are five default flags that every channel implementation must implement<br>
|
|
* SEND_OPTIONS_USE_ACK - Message is sent and an ACK is received when the message has been received by the recipient<br>
|
|
* If no ack is received, the message is not considered successful<br>
|
|
* @see #send(Member[], Serializable , int)
|
|
* @see #send(Member[], Serializable, int, ErrorHandler)
|
|
*/
|
|
public static final int SEND_OPTIONS_USE_ACK = 0x0002;
|
|
|
|
/**
|
|
* 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. <br>
|
|
* However, there are five default flags that every channel implementation must implement<br>
|
|
* SEND_OPTIONS_SYNCHRONIZED_ACK - Message is sent and an ACK is received when the message has been received and
|
|
* processed by the recipient<br>
|
|
* If no ack is received, the message is not considered successful<br>
|
|
* @see #send(Member[], Serializable , int)
|
|
* @see #send(Member[], Serializable, int, ErrorHandler)
|
|
*/
|
|
public static final int SEND_OPTIONS_SYNCHRONIZED_ACK = 0x0004;
|
|
|
|
/**
|
|
* 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. <br>
|
|
* However, there are five default flags that every channel implementation must implement<br>
|
|
* SEND_OPTIONS_ASYNCHRONOUS - Message is sent and an ACK is received when the message has been received and
|
|
* processed by the recipient<br>
|
|
* If no ack is received, the message is not considered successful<br>
|
|
* @see #send(Member[], Serializable , int)
|
|
* @see #send(Member[], Serializable, int, ErrorHandler)
|
|
*/
|
|
public static final int SEND_OPTIONS_ASYNCHRONOUS = 0x0008;
|
|
|
|
/**
|
|
* 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. <br>
|
|
* However, there are five default flags that every channel implementation must implement<br>
|
|
* SEND_OPTIONS_SECURE - Message is sent over an encrypted channel<br>
|
|
* @see #send(Member[], Serializable , int)
|
|
* @see #send(Member[], Serializable, int, ErrorHandler)
|
|
*/
|
|
public static final int SEND_OPTIONS_SECURE = 0x0010;
|
|
|
|
/**
|
|
* Send options. When a message is sent with this flag on
|
|
* the system sends the message using UDP instead of TCP
|
|
* @see #send(Member[], Serializable , int)
|
|
* @see #send(Member[], Serializable, int, ErrorHandler)
|
|
*/
|
|
public static final int SEND_OPTIONS_UDP = 0x0020;
|
|
|
|
/**
|
|
* 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 #send(Member[], Serializable , int)
|
|
* @see #send(Member[], Serializable, int, ErrorHandler)
|
|
*/
|
|
public static final int SEND_OPTIONS_MULTICAST = 0x0040;
|
|
|
|
/**
|
|
* 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. <br>
|
|
* However, there are five default flags that every channel implementation must implement<br>
|
|
* SEND_OPTIONS_DEFAULT - the default sending options, just a helper variable. <br>
|
|
* The default is <code>int SEND_OPTIONS_DEFAULT = SEND_OPTIONS_USE_ACK;</code><br>
|
|
* @see #SEND_OPTIONS_USE_ACK
|
|
* @see #send(Member[], Serializable , int)
|
|
* @see #send(Member[], Serializable, int, ErrorHandler)
|
|
*/
|
|
public static final int SEND_OPTIONS_DEFAULT = SEND_OPTIONS_USE_ACK;
|
|
|
|
|
|
/**
|
|
* Adds an interceptor to the channel message chain.
|
|
* @param interceptor ChannelInterceptor
|
|
*/
|
|
public void addInterceptor(ChannelInterceptor interceptor);
|
|
|
|
/**
|
|
* 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 <BR>
|
|
* DEFAULT - will start all services <BR>
|
|
* MBR_RX_SEQ - starts the membership receiver <BR>
|
|
* MBR_TX_SEQ - starts the membership broadcaster <BR>
|
|
* SND_TX_SEQ - starts the replication transmitter<BR>
|
|
* SND_RX_SEQ - starts the replication receiver<BR>
|
|
* <b>Note:</b> 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 start(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
|
|
* @param svc int value of <BR>
|
|
* DEFAULT - will shutdown all services <BR>
|
|
* MBR_RX_SEQ - stops the membership receiver <BR>
|
|
* MBR_TX_SEQ - stops the membership broadcaster <BR>
|
|
* SND_TX_SEQ - stops the replication transmitter<BR>
|
|
* SND_RX_SEQ - stops the replication receiver<BR>
|
|
* @throws ChannelException if a startup error occurs or the service is already stopped or an error occurs.
|
|
*/
|
|
public void stop(int svc) throws ChannelException;
|
|
|
|
/**
|
|
* Send a message to one or more members in the cluster
|
|
* @param 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.
|
|
* @param msg Serializable - the message to send, has to be serializable, or a <code>ByteMessage</code> 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
|
|
* @throws ChannelException if a serialization error happens.
|
|
* @see ByteMessage
|
|
* @see #SEND_OPTIONS_USE_ACK
|
|
* @see #SEND_OPTIONS_ASYNCHRONOUS
|
|
* @see #SEND_OPTIONS_SYNCHRONIZED_ACK
|
|
*/
|
|
public UniqueId send(Member[] destination, Serializable msg, int options) throws ChannelException;
|
|
|
|
/**
|
|
* 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 UniqueId send(Member[] destination, Serializable msg, int options, ErrorHandler handler) throws ChannelException;
|
|
|
|
/**
|
|
* 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.<br>
|
|
* 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 heartbeat();
|
|
|
|
/**
|
|
* Enables or disables internal heartbeat.
|
|
* @param enable boolean - default value is implementation specific
|
|
* @see #heartbeat()
|
|
*/
|
|
public void setHeartbeat(boolean enable);
|
|
|
|
/**
|
|
* Add a membership listener, will get notified when a new member joins, leaves or crashes
|
|
* <br>If the membership listener implements the Heartbeat interface
|
|
* the <code>heartbeat()</code> method will be invoked when the heartbeat runs on the channel
|
|
* @param listener MembershipListener
|
|
* @see MembershipListener
|
|
*/
|
|
public void addMembershipListener(MembershipListener listener);
|
|
|
|
/**
|
|
* Add a channel listener, this is a callback object when messages are received
|
|
* <br>If the channel listener implements the Heartbeat interface
|
|
* the <code>heartbeat()</code> method will be invoked when the heartbeat runs on the channel
|
|
* @param listener ChannelListener
|
|
* @see ChannelListener
|
|
* @see Heartbeat
|
|
*/
|
|
public void addChannelListener(ChannelListener listener);
|
|
|
|
/**
|
|
* remove a membership listener, listeners are removed based on Object.hashCode and Object.equals
|
|
* @param listener MembershipListener
|
|
* @see MembershipListener
|
|
*/
|
|
public void removeMembershipListener(MembershipListener listener);
|
|
/**
|
|
* remove a channel listener, listeners are removed based on Object.hashCode and Object.equals
|
|
* @param listener ChannelListener
|
|
* @see ChannelListener
|
|
*/
|
|
public void removeChannelListener(ChannelListener listener);
|
|
|
|
/**
|
|
* Returns true if there are any members in the group,
|
|
* this call is the same as <code>getMembers().length > 0</code>
|
|
* @return boolean - true if there are any members automatically discovered
|
|
*/
|
|
public boolean hasMembers() ;
|
|
|
|
/**
|
|
* Get all current group members
|
|
* @return all members or empty array, never null
|
|
*/
|
|
public Member[] getMembers() ;
|
|
|
|
/**
|
|
* 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 getLocalMember(boolean incAlive);
|
|
|
|
/**
|
|
* 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.<br>
|
|
* In most cases, this is not necessary.
|
|
* @param mbr Member
|
|
* @return Member
|
|
*/
|
|
public Member getMember(Member mbr);
|
|
|
|
/**
|
|
* Return the name of this channel.
|
|
* @return channel name
|
|
*/
|
|
public String getName();
|
|
|
|
/**
|
|
* Set the name of this channel
|
|
* @param name The new channel name
|
|
*/
|
|
public void setName(String name);
|
|
|
|
}
|