KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jgroups > Channel


1 // $Id: Channel.java,v 1.6 2004/07/30 04:41:11 jiwils Exp $
2

3 package org.jgroups;
4
5
6 import java.io.Serializable JavaDoc;
7 import java.util.Vector JavaDoc;
8
9
10
11
12 /**
13  A channel represents a group communication endpoint (like BSD datagram sockets). A
14  client joins a group by connecting the channel to a group address and leaves it by
15  disconnecting. Messages sent over the channel are received by all group members that
16  are connected to the same group (that is, all member that have the same group
17  address).<p>
18
19  The FSM for a channel is roughly as follows: a channel is created
20  (<em>unconnected</em>). The channel is connected to a group
21  (<em>connected</em>). Messages can now be sent and received. The channel is
22  disconnected from the group (<em>unconnected</em>). The channel could now be connected to a
23  different group again. The channel is closed (<em>closed</em>).<p>
24
25  Only a single sender is allowed to be connected to a channel at a time, but there can be
26  more than one channel in an application.<p>
27
28  Messages can be sent to the group members using the <em>send</em> method and messages
29  can be received using <em>receive</em> (pull approach).<p>
30
31  A channel instance is created using either a <em>ChannelFactory</em> or the public
32  constructor. Each implementation of a channel must provide a subclass of
33  <code>Channel</code> and an implementation of <code>ChannelFactory</code>. <p>
34  Various degrees of sophistication in message exchange can be achieved using building
35  blocks on top of channels, e.g. light-weight groups, synchronous message invocation,
36  or remote method calls. Channels are on the same abstraction level as sockets, and
37  should really be simple to use. Higher-level abstractions are all built on top of
38  channels.
39
40  @author Bela Ban
41  @see java.net.DatagramPacket
42  @see java.net.MulticastSocket
43  */

44 public abstract class Channel implements Transport {
45     public static final int BLOCK=0;
46     public static final int VIEW=1;
47     public static final int SUSPECT=2;
48     public static final int LOCAL=3;
49     public static final int GET_STATE_EVENTS=4;
50     public static final int AUTO_RECONNECT=5;
51     public static final int AUTO_GETSTATE=6;
52
53
54     protected UpHandler up_handler=null; // when set, <em>all</em> events are passed to it !
55
protected ChannelListener channel_listener=null;
56
57
58     /**
59      Connects the channel to a group. The client is now able to receive group
60      messages, views and block events (depending on the options set) and to send
61      messages to (all or single) group members. This is a null operation if already
62      connected.<p>
63
64      All channels with the same name form a group, that means all messages
65      sent to the group will be received by all channels connected to the same
66      channel name.<p>
67
68      @param channel_name The name of the chanel to connect to.
69      @exception ChannelException The protocol stack cannot be started
70      @exception ChannelClosedException The channel is closed and therefore cannot be used any longer.
71      A new channel has to be created first.
72      @see Channel#disconnect
73      */

74     abstract public void connect(String JavaDoc channel_name) throws ChannelException, ChannelClosedException;
75
76
77     /** Disconnects the channel from the current group (if connected), leaving the group.
78      It is a null operation if not connected. It is a null operation if the channel is closed.
79
80      @see #connect(String) */

81     abstract public void disconnect();
82
83
84     /**
85      Destroys the channel and its associated resources (e.g. the protocol stack). After a channel
86      has been closed, invoking methods on it throws the <code>ChannelClosed</code> exception
87      (or results in a null operation). It is a null operation if the channel is already closed.<p>
88      If the channel is connected to a group, <code>disconnec()t</code> will be called first.
89      */

90     abstract public void close();
91
92
93     /**
94      Re-opens a closed channel. Throws an exception if the channel is already open. After this method
95      returns, connect() may be called to join a group. The address of this member will be different from
96      the previous incarnation.
97      */

98     public void open() throws ChannelException {
99         ;
100     }
101
102
103     /**
104      Determines whether the channel is open, ie. the protocol stack has been created (may not be connected though).
105      */

106     abstract public boolean isOpen();
107
108
109     /**
110      Determines whether the channel is connected to a group. This implies it is open. If true is returned,
111      then the channel can be used to send and receive messages.
112      */

113     abstract public boolean isConnected();
114
115
116     /**
117      * Returns the number of messages that are waiting. Those messages can be
118      * removed by {@link #receive(long)}. Note that this number could change after
119      * calling this method and before calling <tt>receive()</tt> (e.g. the latter
120      * method might be called by a different thread).
121      * @return The number of messages on the queue, or -1 if the queue/channel
122      * is closed/disconnected.
123      */

124     public int getNumMessages() {
125         return -1;
126     }
127
128
129     /** Sends a message to a (unicast) destination. The message contains
130      <ol>
131      <li>a destination address (Address). A <code>null</code> address sends the message
132      to all group members.
133      <li>a source address. Can be left empty. Will be filled in by the protocol stack.
134      <li>a byte buffer. The message contents.
135      <li>several additional fields. They can be used by application programs (or patterns). E.g.
136      a message ID, a <code>oneway</code> field which determines whether a response is
137      expected etc.
138      </ol>
139      @param msg The message to be sent. Destination and buffer should be set. A null destination
140      means to send to all group members.
141
142      @exception ChannelNotConnectedException The channel must be connected to send messages.
143
144      @exception ChannelClosedException The channel is closed and therefore cannot be used any longer.
145      A new channel has to be created first.
146
147      */

148     abstract public void send(Message msg) throws ChannelNotConnectedException, ChannelClosedException;
149
150
151     /**
152      Helper method. Will create a Message(dst, src, obj) and use send(Message).
153      @param dst Destination address for message. If null, message will be sent to all current group members
154      @param src Source (sender's) address. If null, it will be set by the protocol's transport layer before
155      being put on the wire. Can usually be set to null.
156      @param obj Serializable object. Will be serialized into the byte buffer of the Message. If it is <em>
157      not</em> serializable, the byte buffer will be null.
158      */

159     abstract public void send(Address dst, Address src, Serializable JavaDoc obj) throws ChannelNotConnectedException,
160             ChannelClosedException;
161
162
163     /**
164      Access to event mechanism of channels. Enables to send and receive events, used by building
165      blocks to communicate with (building block) specific protocol layers. Currently useful only
166      with JChannel.
167      */

168     public void down(Event evt) {
169     }
170
171
172     /** Receives a message, a view change or a block event. By using <code>setOpt</code>, the
173      type of objects to be received can be determined (e.g. not views and blocks, just
174      messages).
175
176      The possible types returned can be:
177      <ol>
178      <li><code>Message</code>. Normal message
179      <li><code>Event</code>. All other events (used by JChannel)
180      <li><code>View</code>. A view change.
181      <li><code>BlockEvent</code>. A block event indicating an impending view change.
182      <li><code>SuspectEvent</code>. A notification of a suspected member.
183      <li><code>GetStateEvent</code>. The current state of the application should be
184      returned using <code>ReturnState</code>.
185      <li><code>SetStateEvent</code>. The state of a single/all members as requested previously
186      by having called <code>Channel.getState(s).
187      <li><code>ExitEvent</code>. Signals that this member was forced to leave the group (e.g. caused
188      by the member being suspected. The member can rejoin the group by calling
189      open(). If the AUTO_RECONNECT is set (see setOpt()), the reconnect will be
190      done automatically.
191      </ol>
192      The <code>instanceof</code> operator can be used to discriminate between different types
193      returned.
194      @param timeout Value in milliseconds. Value <= 0 means wait forever
195      @return A Message, View, BlockEvent, SuspectEvent, GetStateEvent, SetStateEvent or
196      ExitEvent, depending on what is on top of the internal queue.
197
198      @exception ChannelNotConnectedException The channel must be connected to receive messages.
199
200      @exception ChannelClosedException The channel is closed and therefore cannot be used any longer.
201      A new channel has to be created first.
202
203      @exception TimeoutException Thrown when a timeout has occurred.
204      */

205     abstract public Object JavaDoc receive(long timeout) throws ChannelNotConnectedException,
206             ChannelClosedException, TimeoutException;
207
208
209     /** Returns the next message, view, block, suspect or other event <em>without removing
210      it from the queue</em>.
211      @param timeout Value in milliseconds. Value <= 0 means wait forever
212      @return A Message, View, BlockEvent, SuspectEvent, GetStateEvent or SetStateEvent object,
213      depending on what is on top of the internal queue.
214
215      @exception ChannelNotConnectedException The channel must be connected to receive messages.
216
217      @exception ChannelClosedException The channel is closed and therefore cannot be used any longer.
218      A new channel has to be created first.
219
220      @exception TimeoutException Thrown when a timeout has occurred.
221
222      @see #receive(long)
223      */

224     abstract public Object JavaDoc peek(long timeout) throws ChannelNotConnectedException, ChannelClosedException, TimeoutException;
225
226
227     /**
228      * Gets the current view. This does <em>not</em> retrieve a new view, use
229      <code>receive()</code> to do so. The view may only be available after a successful
230      <code>connect()</code>. The result of calling this method on an unconnected channel
231      is implementation defined (may return null). Calling it on a channel that is not
232      enabled to receive view events (via <code>setOpt</code>) returns
233      <code>null</code>. Calling this method on a closed channel returns a null view.
234      @return The current view.
235      */

236     abstract public View getView();
237
238
239     /**
240      Returns the channel's own address. The result of calling this method on an unconnected
241      channel is implementation defined (may return null). Calling this method on a closed
242      channel returns null.
243
244      @return The channel's address. Generated by the underlying transport, and opaque.
245      Addresses can be used as destination in the <code>Send</code> operation.
246      */

247     abstract public Address getLocalAddress();
248
249
250     /**
251      Returns the group address of the group of which the channel is a member. This is
252      the object that was the argument to <code>Connect</code>. Calling this method on a closed
253      channel returns <code>null</code>.
254
255      @return The group address */

256     abstract public String JavaDoc getChannelName();
257
258
259     /**
260      When up_handler is set, all events will be passed to it directly. These will not be received
261      by the channel (except connect/disconnect, state retrieval and the like). This can be used by
262      building blocks on top of a channel; thus the channel is used as a pass-through medium, and
263      the building blocks take over some of the channel's tasks. However, tasks such as connection
264      management and state transfer is still handled by the channel.
265      */

266     public void setUpHandler(UpHandler up_handler) {
267         this.up_handler=up_handler;
268     }
269
270
271     /**
272      Allows to be notified when a channel event such as connect, disconnect or close occurs.
273      E.g. a PullPushAdapter may choose to stop when the channel is closed, or to start when
274      it is opened.
275      */

276     public void setChannelListener(ChannelListener channel_listener) {
277         this.channel_listener=channel_listener;
278     }
279
280
281     /**
282      Sets an option. The following options are currently recognized:
283      <ol>
284      <li><code>BLOCK</code>. Turn the reception of BLOCK events on/off (value is Boolean).
285      Default is off. If set to on, receiving VIEW events will be set to on, too.
286      <li><code>VIEW</code>. Turn the reception of VIEW events on/off (value is Boolean).
287      Default is on.
288      <li><code>SUSPECT</code>. Turn the reception of SUSPECT events on/off (value is Boolean).
289      Default is on.
290      <li><code>LOCAL</code>. Receive its own broadcast messages to the group
291      (value is Boolean). Default is on.
292      <li><code>GET_STATE_EVENTS</code>. Turn the reception of GetState events on/off
293      (value is Boolean). Default is off, which means that no other members can
294      ask this member for its state (null will be returned).
295      <li><code>AUTO_RECONNECT</code>. Turn auto-reconnection on/off. If on, when a member if forced out
296      of a group (EXIT event), then we will reconnect.
297      <li><code>AUTO_GETSTATE</code>. Turn automatic fetching of state after an auto-reconnect on/off.
298      This also sets AUTO_RECONNECT to true (if not yet set).
299      </ol>
300      This method can be called on an unconnected channel. Calling this method on a
301      closed channel has no effect.
302      */

303     abstract public void setOpt(int option, Object JavaDoc value);
304
305
306     /**
307      Gets an option. This method can be called on an unconnected channel. Calling this
308      method on a closed channel returns <code>null</code>.
309
310      @param option The option to be returned.
311      @return The object associated with an option.
312      */

313     abstract public Object JavaDoc getOpt(int option);
314
315
316     /** Called to acknowledge a block() (callback in <code>MembershipListener</code> or
317      <code>BlockEvent</code> received from call to <code>Receive</code>).
318      After sending BlockOk, no messages should be sent until a new view has been received.
319      Calling this method on a closed channel has no effect.
320      */

321     abstract public void blockOk();
322
323
324     /**
325      Retrieve the state of the group. Will usually contact the oldest group member to get
326      the state. When the method returns true, a <code>SetStateEvent</code> will have been
327      added to the channel's queue, causing <code>receive()</code> to return the state in one of
328      the next invocations. If false, no state will be retrieved by <code>receive()</code>.
329      @param target The address of the member from which the state is to be retrieved. If it is
330      null, the coordinator is contacted.
331      @param timeout Milliseconds to wait for the response (0 = wait indefinitely).
332      @return boolean True if the state was retrieved successfully, otherwise false.
333      @exception ChannelNotConnectedException The channel must be connected to receive messages.
334
335      @exception ChannelClosedException The channel is closed and therefore cannot be used
336      any longer. A new channel has to be created first.
337
338      */

339     abstract public boolean getState(Address target, long timeout)
340             throws ChannelNotConnectedException, ChannelClosedException;
341
342
343     /**
344      Retrieve all states of the group members. Will contact all group members to get
345      the states. When the method returns true, a <code>SetStateEvent</code> will have been
346      added to the channel's queue, causing <code>Receive</code> to return the states in one of
347      the next invocations. If false, no states will be retrieved by <code>Receive</code>.
348      @param targets A list of members which are contacted for states. If the list is null,
349      all the current members of the group will be contacted.
350      @param timeout Milliseconds to wait for the response (0 = wait indefinitely).
351      @return boolean True if the state was retrieved successfully, otherwise false.
352      @exception ChannelNotConnectedException The channel must be connected to
353      receive messages.
354
355      @exception ChannelClosedException The channel is closed and therefore cannot be used
356      any longer. A new channel has to be created first.
357      */

358     abstract public boolean getAllStates(Vector JavaDoc targets, long timeout)
359             throws ChannelNotConnectedException, ChannelClosedException;
360
361
362     /**
363      * Called by the application is response to receiving a
364      * <code>getState()</code> object when calling <code>receive()</code>.
365      * @param state The state of the application as a byte buffer
366      * (to send over the network).
367      */

368     public abstract void returnState(byte[] state);
369
370
371     public static String JavaDoc option2String(int option) {
372         switch(option) {
373             case BLOCK:
374                 return "BLOCK";
375             case VIEW:
376                 return "VIEW";
377             case SUSPECT:
378                 return "SUSPECT";
379             case LOCAL:
380                 return "LOCAL";
381             case GET_STATE_EVENTS:
382                 return "GET_STATE_EVENTS";
383             case AUTO_RECONNECT:
384                 return "AUTO_RECONNECT";
385             case AUTO_GETSTATE:
386                 return "AUTO_GETSTATE";
387             default:
388                 return "unknown (" + option + ')';
389         }
390     }
391 }
392
Popular Tags