001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.catalina.tribes;
018:
019: import java.io.Serializable;
020:
021: /**
022: * Channel interface<br>
023: * A channel is a representation of a group of nodes all participating in some sort of
024: * communication with each other.<br>
025: * The channel is the main API class for Tribes, this is essentially the only class
026: * that an application needs to be aware of. Through the channel the application can:<br>
027: * 1. send messages<br>
028: * 2. receive message (by registering a <code>ChannelListener</code><br>
029: * 3. get all members of the group <code>getMembers()</code><br>
030: * 4. receive notifications of members added and members disappeared by
031: * registerering a <code>MembershipListener</code><br>
032: * <br>
033: * The channel has 5 major components:<br>
034: * 1. Data receiver, with a built in thread pool to receive messages from other peers<br>
035: * 2. Data sender, an implementation for sending data using NIO or java.io<br>
036: * 3. Membership listener,listens for membership broadcasts<br>
037: * 4. Membership broadcaster, broadcasts membership pings.<br>
038: * 5. Channel interceptors, the ability to manipulate messages as they are sent or arrive<br><br>
039: * The channel layout is:
040: * <pre><code>
041: * ChannelListener_1..ChannelListener_N MembershipListener_1..MembershipListener_N [Application Layer]
042: * \ \ / /
043: * \ \ / /
044: * \ \ / /
045: * \ \ / /
046: * \ \ / /
047: * \ \ / /
048: * ---------------------------------------
049: * |
050: * |
051: * Channel
052: * |
053: * ChannelInterceptor_1
054: * | [Channel stack]
055: * ChannelInterceptor_N
056: * |
057: * Coordinator (implements MessageListener,MembershipListener,ChannelInterceptor)
058: * --------------------
059: * / | \
060: * / | \
061: * / | \
062: * / | \
063: * / | \
064: * MembershipService ChannelSender ChannelReceiver [IO layer]
065: * </code></pre>
066: *
067: * For example usage @see org.apache.catalina.tribes.group.GroupChannel
068: * @author Filip Hanik
069: * @version $Revision: 467222 $, $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
070: */
071: public interface Channel {
072:
073: /**
074: * Start and stop sequences can be controlled by these constants
075: * This allows you to start separate components of the channel <br>
076: * DEFAULT - starts or stops all components in the channel
077: * @see #start(int)
078: * @see #stop(int)
079: */
080: public static final int DEFAULT = 15;
081:
082: /**
083: * Start and stop sequences can be controlled by these constants
084: * This allows you to start separate components of the channel <br>
085: * SND_RX_SEQ - starts or stops the data receiver. Start means opening a server socket
086: * in case of a TCP implementation
087: * @see #start(int)
088: * @see #stop(int)
089: */
090: public static final int SND_RX_SEQ = 1;
091:
092: /**
093: * Start and stop sequences can be controlled by these constants
094: * This allows you to start separate components of the channel <br>
095: * SND_TX_SEQ - starts or stops the data sender. This should not open any sockets,
096: * as sockets are opened on demand when a message is being sent
097: * @see #start(int)
098: * @see #stop(int)
099: */
100: public static final int SND_TX_SEQ = 2;
101:
102: /**
103: * Start and stop sequences can be controlled by these constants
104: * This allows you to start separate components of the channel <br>
105: * MBR_RX_SEQ - starts or stops the membership listener. In a multicast implementation
106: * this will open a datagram socket and join a group and listen for membership messages
107: * members joining
108: * @see #start(int)
109: * @see #stop(int)
110: */
111: public static final int MBR_RX_SEQ = 4;
112:
113: /**
114: * Start and stop sequences can be controlled by these constants
115: * This allows you to start separate components of the channel <br>
116: * MBR_TX_SEQ - starts or stops the membership broadcaster. In a multicast implementation
117: * this will open a datagram socket and join a group and broadcast the local member information
118: * @see #start(int)
119: * @see #stop(int)
120: */
121: public static final int MBR_TX_SEQ = 8;
122:
123: /**
124: * Send options, when a message is sent, it can have an option flag
125: * to trigger certain behavior. Most flags are used to trigger channel interceptors
126: * as the message passes through the channel stack. <br>
127: * However, there are five default flags that every channel implementation must implement<br>
128: * SEND_OPTIONS_BYTE_MESSAGE - The message is a pure byte message and no marshalling or unmarshalling will
129: * be performed.<br>
130: *
131: * @see #send(Member[], Serializable , int)
132: * @see #send(Member[], Serializable, int, ErrorHandler)
133: */
134: public static final int SEND_OPTIONS_BYTE_MESSAGE = 0x0001;
135:
136: /**
137: * Send options, when a message is sent, it can have an option flag
138: * to trigger certain behavior. Most flags are used to trigger channel interceptors
139: * as the message passes through the channel stack. <br>
140: * However, there are five default flags that every channel implementation must implement<br>
141: * SEND_OPTIONS_USE_ACK - Message is sent and an ACK is received when the message has been received by the recipient<br>
142: * If no ack is received, the message is not considered successful<br>
143: * @see #send(Member[], Serializable , int)
144: * @see #send(Member[], Serializable, int, ErrorHandler)
145: */
146: public static final int SEND_OPTIONS_USE_ACK = 0x0002;
147:
148: /**
149: * Send options, when a message is sent, it can have an option flag
150: * to trigger certain behavior. Most flags are used to trigger channel interceptors
151: * as the message passes through the channel stack. <br>
152: * However, there are five default flags that every channel implementation must implement<br>
153: * SEND_OPTIONS_SYNCHRONIZED_ACK - Message is sent and an ACK is received when the message has been received and
154: * processed by the recipient<br>
155: * If no ack is received, the message is not considered successful<br>
156: * @see #send(Member[], Serializable , int)
157: * @see #send(Member[], Serializable, int, ErrorHandler)
158: */
159: public static final int SEND_OPTIONS_SYNCHRONIZED_ACK = 0x0004;
160:
161: /**
162: * Send options, when a message is sent, it can have an option flag
163: * to trigger certain behavior. Most flags are used to trigger channel interceptors
164: * as the message passes through the channel stack. <br>
165: * However, there are five default flags that every channel implementation must implement<br>
166: * SEND_OPTIONS_ASYNCHRONOUS - Message is sent and an ACK is received when the message has been received and
167: * processed by the recipient<br>
168: * If no ack is received, the message is not considered successful<br>
169: * @see #send(Member[], Serializable , int)
170: * @see #send(Member[], Serializable, int, ErrorHandler)
171: */
172: public static final int SEND_OPTIONS_ASYNCHRONOUS = 0x0008;
173:
174: /**
175: * Send options, when a message is sent, it can have an option flag
176: * to trigger certain behavior. Most flags are used to trigger channel interceptors
177: * as the message passes through the channel stack. <br>
178: * However, there are five default flags that every channel implementation must implement<br>
179: * SEND_OPTIONS_SECURE - Message is sent over an encrypted channel<br>
180: * @see #send(Member[], Serializable , int)
181: * @see #send(Member[], Serializable, int, ErrorHandler)
182: */
183: public static final int SEND_OPTIONS_SECURE = 0x0010;
184:
185: /**
186: * Send options, when a message is sent, it can have an option flag
187: * to trigger certain behavior. Most flags are used to trigger channel interceptors
188: * as the message passes through the channel stack. <br>
189: * However, there are five default flags that every channel implementation must implement<br>
190: * SEND_OPTIONS_DEFAULT - the default sending options, just a helper variable. <br>
191: * The default is <code>int SEND_OPTIONS_DEFAULT = SEND_OPTIONS_USE_ACK;</code><br>
192: * @see #SEND_OPTIONS_USE_ACK
193: * @see #send(Member[], Serializable , int)
194: * @see #send(Member[], Serializable, int, ErrorHandler)
195: */
196: public static final int SEND_OPTIONS_DEFAULT = SEND_OPTIONS_USE_ACK;
197:
198: /**
199: * Adds an interceptor to the channel message chain.
200: * @param interceptor ChannelInterceptor
201: */
202: public void addInterceptor(ChannelInterceptor interceptor);
203:
204: /**
205: * Starts up the channel. This can be called multiple times for individual services to start
206: * The svc parameter can be the logical or value of any constants
207: * @param svc int value of <BR>
208: * DEFAULT - will start all services <BR>
209: * MBR_RX_SEQ - starts the membership receiver <BR>
210: * MBR_TX_SEQ - starts the membership broadcaster <BR>
211: * SND_TX_SEQ - starts the replication transmitter<BR>
212: * SND_RX_SEQ - starts the replication receiver<BR>
213: * <b>Note:</b> In order for the membership broadcaster to
214: * transmit the correct information, it has to be started after the replication receiver.
215: * @throws ChannelException if a startup error occurs or the service is already started or an error occurs.
216: */
217: public void start(int svc) throws ChannelException;
218:
219: /**
220: * Shuts down the channel. This can be called multiple times for individual services to shutdown
221: * The svc parameter can be the logical or value of any constants
222: * @param svc int value of <BR>
223: * DEFAULT - will shutdown all services <BR>
224: * MBR_RX_SEQ - stops the membership receiver <BR>
225: * MBR_TX_SEQ - stops the membership broadcaster <BR>
226: * SND_TX_SEQ - stops the replication transmitter<BR>
227: * SND_RX_SEQ - stops the replication receiver<BR>
228: * @throws ChannelException if a startup error occurs or the service is already stopped or an error occurs.
229: */
230: public void stop(int svc) throws ChannelException;
231:
232: /**
233: * Send a message to one or more members in the cluster
234: * @param destination Member[] - the destinations, can not be null or zero length, the reason for that
235: * is that a membership change can occur and at that time the application is uncertain what group the message
236: * actually got sent to.
237: * @param msg Serializable - the message to send, has to be serializable, or a <code>ByteMessage</code> to
238: * send a pure byte array
239: * @param options int - sender options, see class documentation for each interceptor that is configured in order to trigger interceptors
240: * @return a unique Id that identifies the message that is sent
241: * @see ByteMessage
242: * @see #SEND_OPTIONS_USE_ACK
243: * @see #SEND_OPTIONS_ASYNCHRONOUS
244: * @see #SEND_OPTIONS_SYNCHRONIZED_ACK
245: */
246: public UniqueId send(Member[] destination, Serializable msg,
247: int options) throws ChannelException;
248:
249: /**
250: * Send a message to one or more members in the cluster
251: * @param destination Member[] - the destinations, null or zero length means all
252: * @param msg ClusterMessage - the message to send
253: * @param options int - sender options, see class documentation
254: * @param handler ErrorHandler - handle errors through a callback, rather than throw it
255: * @return a unique Id that identifies the message that is sent
256: * @exception ChannelException - if a serialization error happens.
257: */
258: public UniqueId send(Member[] destination, Serializable msg,
259: int options, ErrorHandler handler) throws ChannelException;
260:
261: /**
262: * Sends a heart beat through the interceptor stacks
263: * Use this method to alert interceptors and other components to
264: * clean up garbage, timed out messages etc.<br>
265: * If you application has a background thread, then you can save one thread,
266: * by configuring your channel to not use an internal heartbeat thread
267: * and invoking this method.
268: * @see #setHeartbeat(boolean)
269: */
270: public void heartbeat();
271:
272: /**
273: * Enables or disables internal heartbeat.
274: * @param enable boolean - default value is implementation specific
275: * @see #heartbeat()
276: */
277: public void setHeartbeat(boolean enable);
278:
279: /**
280: * Add a membership listener, will get notified when a new member joins, leaves or crashes
281: * <br>If the membership listener implements the Heartbeat interface
282: * the <code>heartbeat()</code> method will be invoked when the heartbeat runs on the channel
283: * @param listener MembershipListener
284: * @see MembershipListener
285: */
286: public void addMembershipListener(MembershipListener listener);
287:
288: /**
289: * Add a channel listener, this is a callback object when messages are received
290: * <br>If the channel listener implements the Heartbeat interface
291: * the <code>heartbeat()</code> method will be invoked when the heartbeat runs on the channel
292: * @param listener ChannelListener
293: * @see ChannelListener
294: * @see Heartbeat
295: */
296: public void addChannelListener(ChannelListener listener);
297:
298: /**
299: * remove a membership listener, listeners are removed based on Object.hashCode and Object.equals
300: * @param listener MembershipListener
301: * @see MembershipListener
302: */
303: public void removeMembershipListener(MembershipListener listener);
304:
305: /**
306: * remove a channel listener, listeners are removed based on Object.hashCode and Object.equals
307: * @param listener ChannelListener
308: * @see ChannelListener
309: */
310: public void removeChannelListener(ChannelListener listener);
311:
312: /**
313: * Returns true if there are any members in the group,
314: * this call is the same as <code>getMembers().length>0</code>
315: * @return boolean - true if there are any members automatically discovered
316: */
317: public boolean hasMembers();
318:
319: /**
320: * Get all current group members
321: * @return all members or empty array, never null
322: */
323: public Member[] getMembers();
324:
325: /**
326: * Return the member that represents this node. This is also the data
327: * that gets broadcasted through the membership broadcaster component
328: * @param incAlive - optimization, true if you want it to calculate alive time
329: * since the membership service started.
330: * @return Member
331: */
332: public Member getLocalMember(boolean incAlive);
333:
334: /**
335: * Returns the member from the membership service with complete and
336: * recent data. Some implementations might serialize and send
337: * membership information along with a message, and instead of sending
338: * complete membership details, only send the primary identifier for the member
339: * but not the payload or other information. When such message is received
340: * the application can retrieve the cached member through this call.<br>
341: * In most cases, this is not necessary.
342: * @param mbr Member
343: * @return Member
344: */
345: public Member getMember(Member mbr);
346:
347: }
|