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  ;
7   import java.util.Vector  ;
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   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   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   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   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   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   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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags