You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by fh...@apache.org on 2006/05/05 20:21:55 UTC
svn commit: r400129 - in /tomcat/container/tc5.5.x/modules/groupcom: ./
src/share/org/apache/catalina/tribes/
src/share/org/apache/catalina/tribes/group/
src/share/org/apache/catalina/tribes/group/interceptors/
Author: fhanik
Date: Fri May 5 11:21:51 2006
New Revision: 400129
URL: http://svn.apache.org/viewcvs?rev=400129&view=rev
Log:
Javadoc the base classes for Tribes.
Also, Channel.send returns a unique Id for the message that was sent so that applications
can track callbacks using the ErrorHandler interface
Added:
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/UniqueId.java
Modified:
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ByteMessage.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Channel.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelException.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelInterceptor.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelListener.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelMessage.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelReceiver.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelSender.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Constants.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ErrorHandler.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ManagedChannel.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Member.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MembershipListener.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MembershipService.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MessageListener.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/RemoteProcessException.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/group/GroupChannel.java
tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/group/interceptors/MessageDispatchInterceptor.java
tomcat/container/tc5.5.x/modules/groupcom/to-do.txt
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ByteMessage.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ByteMessage.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ByteMessage.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ByteMessage.java Fri May 5 11:21:51 2006
@@ -24,36 +24,76 @@
/**
* A byte message is not serialized and deserialized by the channel
* instead it is sent as a byte array<br>
+ * By default Tribes uses java serialization when it receives an object
+ * to be sent over the wire. Java serialization is not the most
+ * efficient of serializing data, and Tribes might not even
+ * have access to the correct class loaders to deserialize the object properly.
+ * <br>
+ * The ByteMessage class is a class where the channel when it receives it will
+ * not attempt to perform serialization, instead it will simply stream the <code>getMessage()</code>
+ * bytes.<br>
+ * If you are using multiple applications on top of Tribes you should add some sort of header
+ * so that you can decide with the <code>ChannelListener.accept()</code> whether this message was intended
+ * for you.
* @author Filip Hanik
* @version $Revision: 304032 $, $Date: 2005-07-27 10:11:55 -0500 (Wed, 27 Jul 2005) $
*/
public class ByteMessage implements Serializable, Externalizable {
+ /**
+ * Storage for the message to be sent
+ */
private byte[] message;
+ /**
+ * Creates an empty byte message
+ * Constructor also for deserialization
+ */
public ByteMessage() {
-
}
+
+ /**
+ * Creates a byte message wit h
+ * @param data byte[] - the message contents
+ */
public ByteMessage(byte[] data) {
message = data;
}
+ /**
+ * Returns the message contents of this byte message
+ * @return byte[] - message contents, can be null
+ */
public byte[] getMessage() {
return message;
}
-
+
+ /**
+ * Sets the message contents of this byte message
+ * @param message byte[]
+ */
public void setMessage(byte[] message) {
this.message = message;
}
+ /**
+ * @see java.io.Externalizable#readExternal
+ * @param in ObjectInput
+ * @throws IOException
+ */
public void readExternal(ObjectInput in ) throws IOException {
int length = in.readInt();
message = new byte[length];
in.read(message,0,length);
}
+ /**
+ * @see java.io.Externalizable#writeExternal
+ * @param out ObjectOutput
+ * @throws IOException
+ */
public void writeExternal(ObjectOutput out) throws IOException {
- out.writeInt(message.length);
+ out.writeInt(message!=null?message.length:0);
out.write(message,0,message.length);
}
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Channel.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Channel.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Channel.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Channel.java Fri May 5 11:21:51 2006
@@ -18,9 +18,52 @@
import java.io.Serializable;
/**
- * Channel interface
- * A channel is an object that manages a group of members.
- * It manages a complete cluster group, both membership and data transfers.
+ * 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
+ * registerering 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
* @author Filip Hanik
* @version $Revision: 304032 $, $Date: 2005-07-27 10:11:55 -0500 (Wed, 27 Jul 2005) $
*/
@@ -28,23 +71,118 @@
/**
* 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 four default flags that every channel implementation must implement<br>
+ * SEND_OPTIONS_BYTE_MESSAGE - The message is a pure byte message and no marshalling or unmarshalling will
+ * be performed.<br>
*
- * Send options
+ * @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 four 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 four 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;
- public static final int SEND_OPTIONS_DEFAULT = 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. <br>
+ * However, there are four 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 four 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;
/**
@@ -62,7 +200,9 @@
* MBR_TX_SEQ - starts the membership broadcaster <BR>
* SND_TX_SEQ - starts the replication transmitter<BR>
* SND_RX_SEQ - starts the replication receiver<BR>
- * @throws ChannelException if a startup error occurs or the service is already started.
+ * <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;
@@ -75,17 +215,25 @@
* 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 started.
+ * @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, null or zero length means all
- * @param msg ClusterMessage - the message to send
- * @param options int - sender options, see class documentation
+ * @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 <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
+ * @see ByteMessage
+ * @see #SEND_OPTIONS_USE_ACK
+ * @see #SEND_OPTIONS_ASYNCHRONOUS
+ * @see #SEND_OPTIONS_SYNCHRONIZED_ACK
*/
- public void send(Member[] destination, Serializable msg, int options) throws ChannelException;
+ public UniqueId send(Member[] destination, Serializable msg, int options) throws ChannelException;
/**
* Send a message to one or more members in the cluster
@@ -93,56 +241,86 @@
* @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 send(Member[] destination, Serializable msg, int options, ErrorHandler handler) throws ChannelException;
+ 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
+ * 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();
/**
- * Add a membership listener, will get notified when a new member joins
+ * 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
* @param listener MembershipListener
+ * @see MembershipListener
*/
public void addMembershipListener(MembershipListener listener);
/**
* Add a channel listener, this is a callback object when messages are received
* @param listener ChannelListener
+ * @see ChannelListener
*/
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);
/**
- * has members
+ * 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 cluster members
- * @return all members or empty array
+ * Get all current group members
+ * @return all members or empty array, never null
*/
public Member[] getMembers() ;
/**
- * Return the member that represents this node.
+ * 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
*/
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelException.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelException.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelException.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelException.java Fri May 5 11:21:51 2006
@@ -16,32 +16,65 @@
package org.apache.catalina.tribes;
import java.util.ArrayList;
-import java.util.Arrays;
/**
- * Channel Exception
+ * Channel Exception<br>
+ * A channel exception is thrown when an internal error happens
+ * somewhere in the channel. <br>
+ * When a global error happens, the cause can be retrieved using <code>getCause()</code><br><br>
+ * If an application is sending a message and some of the recipients fail to receive it,
+ * the application can retrieve what recipients failed by using the <code>getFaultyMembers()</code>
+ * method. This way, an application will always know if a message was delivered successfully or not.
* @author Filip Hanik
* @version $Revision: 304032 $, $Date: 2005-07-27 10:11:55 -0500 (Wed, 27 Jul 2005) $
*/
public class ChannelException extends Exception {
+ /*
+ * Holds a list of faulty members
+ */
private ArrayList faultyMembers=null;
+
+ /**
+ * Constructor, creates a ChannelException
+ * @see java.lang.Exception#Exception()
+ */
public ChannelException() {
super();
}
+ /**
+ * Constructor, creates a ChannelException with an error message
+ * @see java.lang.Exception#Exception(String)
+ */
public ChannelException(String message) {
super(message);
}
+ /**
+ * Constructor, creates a ChannelException with an error message and a cause
+ * @param message String
+ * @param cause Throwable
+ * @see java.lang.Exception#Exception(String,Throwable)
+ */
public ChannelException(String message, Throwable cause) {
super(message, cause);
}
+ /**
+ * Constructor, creates a ChannelException with a cause
+ * @param cause Throwable
+ * @see java.lang.Exception#Exception(Throwable)
+ */
public ChannelException(Throwable cause) {
super(cause);
}
+ /**
+ * Returns the message for this exception
+ * @return String
+ * @see java.lang.Exception#getMessage()
+ */
public String getMessage() {
StringBuffer buf = new StringBuffer(super.getMessage());
if (faultyMembers==null || faultyMembers.size() == 0 ) {
@@ -57,26 +90,53 @@
return buf.toString();
}
+ /**
+ * Adds a faulty member, and the reason the member failed.
+ * @param mbr Member
+ * @param x Exception
+ */
public void addFaultyMember(Member mbr, Exception x ) {
addFaultyMember(new FaultyMember(mbr,x));
}
+ /**
+ * Adds a list of faulty members
+ * @param mbrs FaultyMember[]
+ */
public void addFaultyMember(FaultyMember[] mbrs) {
for (int i=0; mbrs!=null && i<mbrs.length; i++ ) {
addFaultyMember(mbrs[i]);
}
}
+ /**
+ * Adds a faulty member
+ * @param mbr FaultyMember
+ */
public void addFaultyMember(FaultyMember mbr) {
if ( this.faultyMembers==null ) this.faultyMembers = new ArrayList();
faultyMembers.add(mbr);
}
-
+
+ /**
+ * Returns an array of members that failed and the reason they failed.
+ * @return FaultyMember[]
+ */
public FaultyMember[] getFaultyMembers() {
if ( this.faultyMembers==null ) return new FaultyMember[0];
return (FaultyMember[])faultyMembers.toArray(new FaultyMember[faultyMembers.size()]);
}
+ /**
+ *
+ * <p>Title: FaultyMember class</p>
+ *
+ * <p>Description: Represent a failure to a specific member when a message was sent
+ * to more than one member</p>
+ *
+ * @author Filip Hanik
+ * @version 1.0
+ */
public static class FaultyMember {
protected Exception cause;
protected Member member;
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelInterceptor.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelInterceptor.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelInterceptor.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelInterceptor.java Fri May 5 11:21:51 2006
@@ -18,52 +18,124 @@
import org.apache.catalina.tribes.group.InterceptorPayload;
/**
- * Abstract class for the interceptor base class.
+ * A ChannelInterceptor is an interceptor that intercepts
+ * messages and membership messages in the channel stack.
+ * This allows interceptors to modify the message or perform
+ * other actions when a message is sent or received.<br>
+ * Interceptors are tied together in a linked list.
+ * @see org.apache.catalina.tribes.group.ChannelInterceptorBase
* @author Filip Hanik
* @version $Revision: 304032 $, $Date: 2005-07-27 10:11:55 -0500 (Wed, 27 Jul 2005) $
*/
public interface ChannelInterceptor extends MembershipListener {
+ /**
+ * An interceptor can react to a message based on a set bit on the
+ * message options. <br>
+ * When a message is sent, the options can be retrieved from ChannelMessage.getOptions()
+ * and if the bit is set, this interceptor will react to it.<br>
+ * A simple evaluation if an interceptor should react to the message would be:<br>
+ * <code>boolean react = (getOptionFlag() == (getOptionFlag() & ChannelMessage.getOptions()));</code><br>
+ * The default option is 0, meaning there is no way for the application to trigger the
+ * interceptor. The interceptor itself will decide.<br>
+ * @return int
+ * @see ChannelMessage#getOptions()
+ */
public int getOptionFlag();
+
+ /**
+ * Sets the option flag
+ * @param flag int
+ * @see #getOptionFlag()
+ */
public void setOptionFlag(int flag);
+ /**
+ * Set the next interceptor in the list of interceptors
+ * @param next ChannelInterceptor
+ */
public void setNext(ChannelInterceptor next) ;
+ /**
+ * Retrieve the next interceptor in the list
+ * @return ChannelInterceptor - returns the next interceptor in the list or null if no more interceptors exist
+ */
public ChannelInterceptor getNext();
+ /**
+ * Set the previous interceptor in the list
+ * @param previous ChannelInterceptor
+ */
public void setPrevious(ChannelInterceptor previous);
+ /**
+ * Retrieve the previous interceptor in the list
+ * @return ChannelInterceptor - returns the previous interceptor in the list or null if no more interceptors exist
+ */
public ChannelInterceptor getPrevious();
+ /**
+ * The <code>sendMessage</code> method is called when a message is being sent to one more destinations.
+ * The interceptor can modify any of the parameters and then pass on the message down the stack by
+ * invoking <code>getNext().sendMessage(destination,msg,payload)</code><br>
+ * Alternatively the interceptor can stop the message from being sent by not invoking
+ * <code>getNext().sendMessage(destination,msg,payload)</code><br>
+ * If the message is to be sent asynchronous the application can be notified of completion and
+ * errors by passing in an error handler attached to a payload object.<br>
+ * The ChannelMessage.getAddress contains Channel.getLocalMember, and can be overwritten
+ * to simulate a message sent from another node.<br>
+ * @param destination Member[] - the destination for this message
+ * @param msg ChannelMessage - the message to be sent
+ * @param payload InterceptorPayload - the payload, carrying an error handler and future useful data, can be null
+ * @throws ChannelException
+ * @see ErrorHandler
+ * @see InterceptorPayload
+ */
public void sendMessage(Member[] destination, ChannelMessage msg, InterceptorPayload payload) throws ChannelException;
+ /**
+ * the <code>messageReceived</code> is invoked when a message is received.
+ * <code>ChannelMessage.getAddress()</code> is the sender, or the reply-to address
+ * if it has been overwritten.
+ * @param data ChannelMessage
+ */
public void messageReceived(ChannelMessage data);
+ /**
+ * The <code>heartbeat()</code> method gets invoked periodically
+ * to allow interceptors to clean up resources, time out object and
+ * perform actions that are unrelated to sending/receiving data.
+ */
public void heartbeat();
/**
- * has members
+ * Intercepts the <code>Channel.hasMembers()</code> method
+ * @return boolean - if the channel has members in its membership group
+ * @see Channel#hasMembers()
*/
public boolean hasMembers() ;
/**
- * Get all current cluster members
- * @return all members or empty array
+ * Intercepts the code>Channel.getMembers()</code> method
+ * @return Member[]
+ * @see Channel#getMembers()
*/
public Member[] getMembers() ;
/**
- * Return the member that represents this node.
- *
+ * Intercepts the code>Channel.getLocalMember(boolean)</code> method
+ * @param incAliveTime boolean
* @return Member
+ * @see Channel#getLocalMember(boolean)
*/
public Member getLocalMember(boolean incAliveTime) ;
/**
- *
+ * Intercepts the code>Channel.getMember(Member)</code> method
* @param mbr Member
* @return Member - the actual member information, including stay alive
+ * @see Channel#getMember(Member)
*/
public Member getMember(Member mbr);
@@ -71,12 +143,13 @@
* 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>
+ * Channel.DEFAULT - will start all services <BR>
+ * Channel.MBR_RX_SEQ - starts the membership receiver <BR>
+ * Channel.MBR_TX_SEQ - starts the membership broadcaster <BR>
+ * Channel.SND_TX_SEQ - starts the replication transmitter<BR>
+ * Channel.SND_RX_SEQ - starts the replication receiver<BR>
* @throws ChannelException if a startup error occurs or the service is already started.
+ * @see Channel
*/
public void start(int svc) throws ChannelException;
@@ -84,12 +157,13 @@
* 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>
+ * Channel.DEFAULT - will shutdown all services <BR>
+ * Channel.MBR_RX_SEQ - stops the membership receiver <BR>
+ * Channel.MBR_TX_SEQ - stops the membership broadcaster <BR>
+ * Channel.SND_TX_SEQ - stops the replication transmitter<BR>
+ * Channel.SND_RX_SEQ - stops the replication receiver<BR>
* @throws ChannelException if a startup error occurs or the service is already started.
+ * @see Channel
*/
public void stop(int svc) throws ChannelException;
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelListener.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelListener.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelListener.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelListener.java Fri May 5 11:21:51 2006
@@ -16,22 +16,52 @@
package org.apache.catalina.tribes;
import java.io.Serializable;
+/**
+ *
+ * <p>Title: ChannelListener</p>
+ *
+ * <p>Description: An interface to listens to incoming messages from a channel </p>
+ * When a message is received, the Channel will invoke the channel listener in a conditional sequence.
+ * <code>if ( listener.accept(msg,sender) ) listener.messageReceived(msg,sender);</code><br>
+ * A ChannelListener implementation MUST NOT return true on <code>accept(Serializable, Member)</code>
+ * if it doesn't intend to process the message. The channel can this way track whether a message
+ * was processed by an above application or if it was just received and forgot about, a featuer required
+ * to support message-response(RPC) calls<br>
+ *
+ * @author Filip Hanik
+ * @version 1.0
+ */
public interface ChannelListener {
/**
- * Receive a message from the cluster.
- * @param msg ClusterMessage
- * @return ClusterMessage - response to the message sent. <br>
- * The response object may be ignored and is not required for the
- * implementation to send back to the sender.
+ * Receive a message from the channel
+ * @param msg Serializable
+ * @param sender - the source of the message
*/
public void messageReceived(Serializable msg, Member sender);
+ /**
+ * Invoked by the channel to determine if the listener will process this message or not.
+ * @param msg Serializable
+ * @param sender Member
+ * @return boolean
+ */
public boolean accept(Serializable msg, Member sender);
+ /**
+ *
+ * @param listener Object
+ * @return boolean
+ * @see Object#equals(Object)
+ */
public boolean equals(Object listener);
+ /**
+ *
+ * @return int
+ * @see Object#hashCode(int)
+ */
public int hashCode();
}
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelMessage.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelMessage.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelMessage.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelMessage.java Fri May 5 11:21:51 2006
@@ -28,58 +28,77 @@
/**
- * Get the address that this message originated from. This would be set
+ * Get the address that this message originated from.
+ * Almost always <code>Channel.getLocalMember(boolean)</code><br>
+ * This would be set to a different address
* if the message was being relayed from a host other than the one
* that originally sent it.
+ * @return the source or reply-to address of this message
*/
public Member getAddress();
/**
- * Called by the cluster before sending it to the other
- * nodes.
- *
+ * Sets the source or reply-to address of this message
* @param member Member
*/
public void setAddress(Member member);
/**
- * Timestamp message.
- *
- * @return long
+ * Timestamp of when the message was created.
+ * @return long timestamp in milliseconds
*/
public long getTimestamp();
/**
- * Called by the cluster before sending out
- * the message.
*
+ * Sets the timestamp of this message
* @param timestamp The timestamp
*/
public void setTimestamp(long timestamp);
/**
- * Each message must have a unique ID, in case of using async replication,
- * and a smart queue, this id is used to replace messages not yet sent.
- *
+ * Each message must have a globally unique Id.
+ * interceptors heavily depend on this id for message processing
* @return byte
*/
public byte[] getUniqueId();
+ /**
+ * The byte buffer that contains the actual message payload
+ * @param buf XByteBuffer
+ */
public void setMessage(XByteBuffer buf);
+ /**
+ * returns the byte buffer that contains the actual message payload
+ * @return XByteBuffer
+ */
public XByteBuffer getMessage();
+ /**
+ * The message options is a 32 bit flag set
+ * that triggers interceptors and message behavior.
+ * @see Channel#send(Member[], Serializable, int)
+ * @see ChannelInterceptor#getOptionFlag
+ * @return int - the option bits set for this message
+ */
public int getOptions();
+
+ /**
+ * sets the option bits for this message
+ * @param options int
+ * @see #getOptions()
+ */
public void setOptions(int options);
/**
- * Shallow clone, only the actual message(getMessage()) is cloned, the rest remains as references
+ * Shallow clone, what gets cloned depends on the implementation
* @return ChannelMessage
*/
public Object clone();
/**
- * Deep clone, everything gets cloned
+ * Deep clone, all fields MUST get cloned
* @return ChannelMessage
*/
public Object deepclone();
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelReceiver.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelReceiver.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelReceiver.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelReceiver.java Fri May 5 11:21:51 2006
@@ -18,36 +18,51 @@
/**
- * Cluster Receiver Interface
+ * ChannelReceiver Interface<br>
+ * The <code>ChannelReceiver</code> interface is the data receiver component
+ * at the bottom layer, the IO layer (for layers see the javadoc for the {@link Channel} interface).
+ * This class may optionally implement a thread pool for parallel processing of incoming messages.
* @author Filip Hanik
* @version $Revision: 379904 $, $Date: 2006-02-22 15:16:25 -0600 (Wed, 22 Feb 2006) $
*/
public interface ChannelReceiver {
/**
- * Start message listing
+ * Start listening for incoming messages on the host/port
* @throws java.io.IOException
*/
public void start() throws java.io.IOException;
/**
- * Stop message listing
+ * Stop listening for messages
*/
public void stop();
/**
- * get the listing ip interface
- * @return The host
+ * String representation of the IPv4 or IPv6 address that this host is listening
+ * to.
+ * @return the host that this receiver is listening to
*/
public String getHost();
/**
- * get the listing ip port
- * @return The port
+ * Returns the listening port
+ * @return port
*/
public int getPort();
+ /**
+ * Sets the message listener to receive notification of incoming
+ * @param listener MessageListener
+ * @see MessageListener
+ */
public void setMessageListener(MessageListener listener);
+
+ /**
+ * Returns the message listener that is associated with this receiver
+ * @return MessageListener
+ * @see MessageListener
+ */
public MessageListener getMessageListener();
}
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelSender.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelSender.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelSender.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ChannelSender.java Fri May 5 11:21:51 2006
@@ -18,17 +18,51 @@
/**
- *
+ * ChannelReceiver Interface<br>
+ * The <code>ChannelSender</code> interface is the data sender component
+ * at the bottom layer, the IO layer (for layers see the javadoc for the {@link Channel} interface).<br>
+ * The channel sender must support "silent" members, ie, be able to send a message to a member
+ * that is not in the membership, but is part of the destination parameter
* @author Filip Hanik
- * @version $Revision: 303950 $, $Date: 2005-06-09 15:38:30 -0500 (Thu, 09 Jun 2005) $
- *
- */
+ * @version $Revision: 379904 $, $Date: 2006-02-22 15:16:25 -0600 (Wed, 22 Feb 2006) $
+ */
public interface ChannelSender
{
+ /**
+ * Notify the sender of a member being added to the group.<br>
+ * Optional. This can be an empty implementation, that does nothing
+ * @param member Member
+ */
public void add(Member member);
+ /**
+ * Notification that a member has been removed or crashed.
+ * Can be used to clean up open connections etc
+ * @param member Member
+ */
public void remove(Member member);
+
+ /**
+ * Start the channel sender
+ * @throws IOException if preprocessing takes place and an error happens
+ */
public void start() throws java.io.IOException;
+ /**
+ * Stop the channel sender
+ */
public void stop();
+
+ /**
+ * A channel heartbeat, use this method to clean up resources
+ */
public void heartbeat() ;
+
+ /**
+ * Send a message to one or more recipients.
+ * @param message ChannelMessage - the message to be sent
+ * @param destination Member[] - the destinations
+ * @throws ChannelException - if an error happens, the ChannelSender MUST report
+ * individual send failures on a per member basis, using ChannelException.addFaultyMember
+ * @see ChannelException#addFaultyMember(Member,java.lang.Exception)
+ */
public void sendMessage(ChannelMessage message, Member[] destination) throws ChannelException;
}
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Constants.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Constants.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Constants.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Constants.java Fri May 5 11:21:51 2006
@@ -22,6 +22,7 @@
* package.
*
* @author Bip Thelin
+ * @author Filip Hanik
* @version $Revision: 302726 $, $Date: 2004-02-27 08:59:07 -0600 (Fri, 27 Feb 2004) $
*/
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ErrorHandler.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ErrorHandler.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ErrorHandler.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ErrorHandler.java Fri May 5 11:21:51 2006
@@ -16,10 +16,12 @@
package org.apache.catalina.tribes;
-import java.io.Serializable;
+
/**
- *
+ * The <code>ErrorHandler</code> class is used when sending messages
+ * that are sent asynchronously and the application still needs to get
+ * confirmation when the message was sent successfully or when a message errored out.
* @author Filip Hanik
* @version 1.0
*/
@@ -27,17 +29,17 @@
/**
* Invoked if the message is dispatched asynch, and an error occurs
- * @param x Exception
- * @param destination Member[]
- * @param msg Serializable
+ * @param x ChannelException - the error that happened
+ * @param id - the unique id for the message
+ * @see Channel#send(Member[], Serializable, int, ErrorHandler)
*/
- public void handleError(Exception x, Member[] destination, Serializable msg);
+ public void handleError(ChannelException x, UniqueId id);
/**
- * Invoked when the message has been sent.
- * @param destination Member[]
- * @param msg Serializable
+ * Invoked when the message has been sent successfully.
+ * @param id - the unique id for the message
+ * @see Channel#send(Member[], Serializable, int, ErrorHandler)
*/
- public void handleCompletion(Member[] destination, Serializable msg);
+ public void handleCompletion(UniqueId id);
}
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ManagedChannel.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ManagedChannel.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ManagedChannel.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/ManagedChannel.java Fri May 5 11:21:51 2006
@@ -15,26 +15,63 @@
*/
package org.apache.catalina.tribes;
-import java.io.Serializable;
import java.util.Iterator;
/**
* Channel interface
* A managed channel interface gives you access to the components of the channels
- * such as senders, receivers, interceptors etc
+ * such as senders, receivers, interceptors etc for configurations purposes
* @author Filip Hanik
* @version $Revision: 304032 $, $Date: 2005-07-27 10:11:55 -0500 (Wed, 27 Jul 2005) $
*/
public interface ManagedChannel extends Channel {
-
+ /**
+ * Sets the channel sender
+ * @param sender ChannelSender
+ * @see ChannelSender
+ */
public void setChannelSender(ChannelSender sender);
+
+ /**
+ * Sets the channel receiver
+ * @param receiver ChannelReceiver
+ * @see ChannelReceiver
+ */
public void setChannelReceiver(ChannelReceiver receiver);
+
+ /**
+ * Sets the membership service
+ * @param service MembershipService
+ * @see MembershipService
+ */
public void setMembershipService(MembershipService service);
+ /**
+ * returns the channel sender
+ * @return ChannelSender
+ * @see ChannelSender
+ */
public ChannelSender getChannelSender();
+
+ /**
+ * returns the channel receiver
+ * @return ChannelReceiver
+ * @see ChannelReceiver
+ */
public ChannelReceiver getChannelReceiver();
+
+ /**
+ * Returns the membership service
+ * @return MembershipService
+ * @see MembershipService
+ */
public MembershipService getMembershipService();
+ /**
+ * Returns the interceptor stack
+ * @return Iterator
+ * @see Channel#addInterceptor(ChannelInterceptor)
+ */
public Iterator getInterceptors();
}
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Member.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Member.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Member.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/Member.java Fri May 5 11:21:51 2006
@@ -17,14 +17,14 @@
package org.apache.catalina.tribes;
/**
- * The Member interface, defines a member in the Cluster.
- * A member is a Tomcat process that participates in session replication.<BR>
+ * The Member interface, defines a member in the group.
* Each member can carry a set of properties, defined by the actual implementation.<BR>
- * For TCP replication has been targeted for the first release, the hostname and listen port
- * of the member is defined as hardcoded stuff.<BR>
- * The Member interface together with MembershipListener, MembershipService are interfaces used to
- * switch out the service used to establish membership in between the cluster nodes.
- *
+ * A member is identified by the host/ip/uniqueId<br>
+ * The host is what interface the member is listening to, to receive data<br>
+ * The port is what port the member is listening to, to receive data<br>
+ * The uniqueId defines the session id for the member. This is an important feature
+ * since a member that has crashed and the starts up again on the same port/host is
+ * not guaranteed to be the same member, so no state transfers will ever be confused
* @author Filip Hanik
* @version $Revision: 303950 $, $Date: 2005-06-09 15:38:30 -0500 (Thu, 09 Jun 2005) $
*/
@@ -34,43 +34,66 @@
/**
* When a member leaves the cluster, the payload of the memberDisappeared member
- * will be the following bytes.
+ * will be the following bytes. This indicates a soft shutdown, and not a crash
*/
public static final byte[] SHUTDOWN_PAYLOAD = new byte[] {66, 65, 66, 89, 45, 65, 76, 69, 88};
/**
* Return implementation specific properties about this cluster node.
+ * @return a hashmap of specific properties, implementation specific
*/
public java.util.HashMap getMemberProperties();
+
/**
- * Returns the name of this node, should be unique within the cluster.
+ * Returns the name of this node, should be unique within the group.
*/
public String getName();
/**
* Returns the name of the cluster domain from this node
+ * @deprecated domains and partitioning will not be handled
+ * by the membership service in the future<br>
+ * To broadcast a domain use the payload feature of the membership service
*/
public String getDomain();
/**
- * Returns the TCP listen host for the TCP implementation
+ * Returns the listen host for the ChannelReceiver implementation
+ * @return IPv4 or IPv6 representation of the host address this member listens to incoming data
+ * @see ChannelReceiver
*/
public byte[] getHost();
+
/**
- * Returns the TCP listen portfor the TCP implementation
+ * Returns the listen port for the ChannelReceiver implementation
+ * @return IPv4 or IPv6 representation of the host address this member listens to incoming data
+ * @see ChannelReceiver
*/
public int getPort();
/**
* Contains information on how long this member has been online.
* The result is the number of milli seconds this member has been
- * broadcasting its membership to the cluster.
+ * broadcasting its membership to the group.
* @return nr of milliseconds since this member started.
*/
public long getMemberAliveTime();
+ /**
+ * The current state of the member
+ * @return boolean - true if the member is functioning correctly
+ */
public boolean isReady();
+ /**
+ * The current state of the member
+ * @return boolean - true if the member is suspect, but the crash has not been confirmed
+ */
public boolean isSuspect();
+
+ /**
+ *
+ * @return boolean - true if the member has been confirmed to malfunction
+ */
public boolean isFailing();
/**
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MembershipListener.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MembershipListener.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MembershipListener.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MembershipListener.java Fri May 5 11:21:51 2006
@@ -19,7 +19,7 @@
/**
* The MembershipListener interface is used as a callback to the
* membership service. It has two methods that will notify the listener
- * when a member has joined the cluster and when a member has disappeared (crashed)
+ * when a member has joined the group and when a member has disappeared (crashed)
*
* @author Filip Hanik
* @version $Revision: 302726 $, $Date: 2004-02-27 08:59:07 -0600 (Fri, 27 Feb 2004) $
@@ -27,7 +27,18 @@
public interface MembershipListener {
+ /**
+ * A member was added to the group
+ * @param member Member - the member that was added
+ */
public void memberAdded(Member member);
+
+ /**
+ * A member was removed from the group<br>
+ * If the member left voluntarily, the payload will contain the Member.SHUTDOWN_PAYLOAD data
+ * @param member Member
+ * @see Member#SHUTDOWN_PAYLOAD
+ */
public void memberDisappeared(Member member);
}
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MembershipService.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MembershipService.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MembershipService.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MembershipService.java Fri May 5 11:21:51 2006
@@ -18,8 +18,9 @@
/**
- * The membership service helps the cluster determine the membership
- * logic in the cluster.
+ * MembershipService Interface<br>
+ * The <code>MembershipService</code> interface is the membership component
+ * at the bottom layer, the IO layer (for layers see the javadoc for the {@link Channel} interface).<br>
* @author Filip Hanik
* @version $Revision: 378093 $, $Date: 2006-02-15 15:13:45 -0600 (Wed, 15 Feb 2006) $
*/
@@ -72,11 +73,16 @@
public void stop(int level);
/**
- * Returns that cluster has members.
+ * @return true if the the group contains members
*/
public boolean hasMembers();
+ /**
+ *
+ * @param mbr Member
+ * @return Member
+ */
public Member getMember(Member mbr);
/**
* Returns a list of all the members in the cluster.
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MessageListener.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MessageListener.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MessageListener.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/MessageListener.java Fri May 5 11:21:51 2006
@@ -15,16 +15,21 @@
*/
package org.apache.catalina.tribes;
-import java.io.Serializable;
+/**
+ *
+ * <p>Title: MessageListener</p>
+ *
+ * <p>Description: The listener to be registered with the ChannelReceiver, internal Tribes component</p>
+ *
+ * @author Filip Hanik
+ * @version 1.0
+ */
public interface MessageListener {
/**
- * Receive a message from the cluster.
- * @param msg ClusterMessage
- * @return ClusterMessage - response to the message sent. <br>
- * The response object may be ignored and is not required for the
- * implementation to send back to the sender.
+ * Receive a message from the IO components in the Channel stack
+ * @param msg ChannelMessage
*/
public void messageReceived(ChannelMessage msg);
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/RemoteProcessException.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/RemoteProcessException.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/RemoteProcessException.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/RemoteProcessException.java Fri May 5 11:21:51 2006
@@ -20,13 +20,13 @@
*
* <p>Description: Message thrown by a sender when USE_SYNC_ACK receives a FAIL_ACK_COMMAND.<br>
* This means that the message was received on the remote node but the processing of the message failed.
+ * This message will be embedded in a ChannelException.FaultyMember
* </p>
- *
+ * @see ChannelException
* @author Filip Hanik
* @version 1.0
*/
-public class RemoteProcessException
- extends RuntimeException {
+public class RemoteProcessException extends RuntimeException {
public RemoteProcessException() {
super();
}
Added: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/UniqueId.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/UniqueId.java?rev=400129&view=auto
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/UniqueId.java (added)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/UniqueId.java Fri May 5 11:21:51 2006
@@ -0,0 +1,54 @@
+/*
+ * Copyright 1999,2004-2005 The Apache Software Foundation.
+ *
+ * Licensed 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.util.Arrays;
+
+/**
+ * <p>Title: Represents a globabally unique Id</p>
+ *
+ * <p>Company: </p>
+ *
+ * @author Filip Hanik
+ * @version 1.0
+ */
+public class UniqueId {
+ protected byte[] id;
+
+ public UniqueId() {
+ }
+
+ public UniqueId(byte[] id) {
+ }
+
+ public int hashCode() {
+ if ( id == null ) return 0;
+ return Arrays.hashCode(id);
+ }
+
+ public boolean equals(Object other) {
+ boolean result = (other instanceof UniqueId);
+ if ( result ) {
+ UniqueId uid = (UniqueId)other;
+ if ( this.id == null && uid.id == null ) result = true;
+ else if ( this.id == null && uid.id != null ) result = false;
+ else if ( this.id != null && uid.id == null ) result = false;
+ else result = Arrays.equals(this.id,uid.id);
+ }//end if
+ return result;
+ }
+
+}
\ No newline at end of file
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/group/GroupChannel.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/group/GroupChannel.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/group/GroupChannel.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/group/GroupChannel.java Fri May 5 11:21:51 2006
@@ -36,6 +36,7 @@
import org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor;
import org.apache.catalina.tribes.io.ClusterData;
import org.apache.catalina.tribes.io.XByteBuffer;
+import org.apache.catalina.tribes.UniqueId;
/**
* The GroupChannel manages the replication channel. It coordinates
@@ -46,7 +47,7 @@
* @version $Revision: 304032 $, $Date: 2005-07-27 10:11:55 -0500 (Wed, 27 Jul 2005) $
*/
public class GroupChannel extends ChannelInterceptorBase implements ManagedChannel {
- protected boolean heartbeatEnabled = true;
+ private boolean heartbeat = true;
protected long heartbeatSleeptime = 60*1000;//only run once a minute
protected HeartbeatThread hbthread = null;
@@ -57,6 +58,7 @@
private ArrayList channelListeners = new ArrayList();
private boolean optionCheck = false;
+
public GroupChannel() {
addInterceptor(this);
}
@@ -96,15 +98,14 @@
* @param options int - sender options, see class documentation
* @return ClusterMessage[] - the replies from the members, if any.
*/
- public void send(Member[] destination, Serializable msg, int options) throws ChannelException {
- send(destination,msg,options,null);
+ public UniqueId send(Member[] destination, Serializable msg, int options) throws ChannelException {
+ return send(destination,msg,options,null);
}
- public void send(Member[] destination, Serializable msg, int options, ErrorHandler handler) throws ChannelException {
- if ( msg == null ) return;
+ public UniqueId send(Member[] destination, Serializable msg, int options, ErrorHandler handler) throws ChannelException {
+ if ( msg == null ) throw new ChannelException("Cant send a NULL message");
try {
- if ( destination == null ) throw new ChannelException("No destination given");
- if ( destination.length == 0 ) return;
- ClusterData data = new ClusterData();//generates a unique Id
+ if ( destination == null || destination.length == 0) throw new ChannelException("No destination given");
+ ClusterData data = new ClusterData(true);//generates a unique Id
data.setAddress(getLocalMember(false));
data.setTimestamp(System.currentTimeMillis());
byte[] b = null;
@@ -124,6 +125,7 @@
payload.setErrorHandler(handler);
}
getFirstInterceptor().sendMessage(destination, data, payload);
+ return new UniqueId(data.getUniqueId());
}catch ( Exception x ) {
if ( x instanceof ChannelException ) throw (ChannelException)x;
throw new ChannelException(x);
@@ -241,7 +243,7 @@
setupDefaultStack();
if (optionCheck) checkOptionFlags();
super.start(svc);
- if ( hbthread == null && heartbeatEnabled ) {
+ if ( hbthread == null && heartbeat ) {
hbthread = new HeartbeatThread(this,heartbeatSleeptime);
hbthread.start();
}
@@ -310,20 +312,20 @@
this.optionCheck = optionCheck;
}
- public void setHeartbeatEnabled(boolean heartbeatEnabled) {
- this.heartbeatEnabled = heartbeatEnabled;
- }
-
public void setHeartbeatSleeptime(long heartbeatSleeptime) {
this.heartbeatSleeptime = heartbeatSleeptime;
}
+ public void setHeartbeat(boolean heartbeat) {
+ this.heartbeat = heartbeat;
+ }
+
public boolean getOptionCheck() {
return optionCheck;
}
- public boolean getHeartbeatEnabled() {
- return heartbeatEnabled;
+ public boolean getHeartbeat() {
+ return heartbeat;
}
public long getHeartbeatSleeptime() {
Modified: tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/group/interceptors/MessageDispatchInterceptor.java
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/group/interceptors/MessageDispatchInterceptor.java?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/group/interceptors/MessageDispatchInterceptor.java (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/src/share/org/apache/catalina/tribes/group/interceptors/MessageDispatchInterceptor.java Fri May 5 11:21:51 2006
@@ -23,6 +23,7 @@
import org.apache.catalina.tribes.group.InterceptorPayload;
import org.apache.catalina.tribes.transport.bio.util.FastQueue;
import org.apache.catalina.tribes.transport.bio.util.LinkObject;
+import org.apache.catalina.tribes.UniqueId;
/**
*
@@ -144,14 +145,17 @@
try {
super.sendMessage(destination,msg,null);
try {
- if ( link.getHandler() != null ) link.getHandler().handleCompletion(destination,msg);
+ if ( link.getHandler() != null ) link.getHandler().handleCompletion(new UniqueId(msg.getUniqueId()));
} catch ( Exception ex ) {
log.error("Unable to report back completed message.",ex);
}
} catch ( Exception x ) {
+ ChannelException cx = null;
+ if ( x instanceof ChannelException ) cx = (ChannelException)x;
+ else cx = new ChannelException(x);
if ( log.isDebugEnabled() ) log.debug("Error while processing async message.",x);
try {
- if (link.getHandler() != null) link.getHandler().handleError(x, destination, msg);
+ if (link.getHandler() != null) link.getHandler().handleError(cx, new UniqueId(msg.getUniqueId()));
} catch ( Exception ex ) {
log.error("Unable to report back error message.",ex);
}
Modified: tomcat/container/tc5.5.x/modules/groupcom/to-do.txt
URL: http://svn.apache.org/viewcvs/tomcat/container/tc5.5.x/modules/groupcom/to-do.txt?rev=400129&r1=400128&r2=400129&view=diff
==============================================================================
--- tomcat/container/tc5.5.x/modules/groupcom/to-do.txt (original)
+++ tomcat/container/tc5.5.x/modules/groupcom/to-do.txt Fri May 5 11:21:51 2006
@@ -40,6 +40,9 @@
Code Tasks:
===========================================
+45. McastServiceImpl.receive should have a SO_TIMEOUT so that we can check
+ for members dropping on the same thread
+
44. Soft membership failure detection, ie if a webapp is stopped, but
the AbstractReplicatedMap doesn't broadcast a stop message
This is one potential solution:
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org