channel.java

JGRoups源码

// $Id: Channel.java,v 1.25 2006/10/26 15:07:34 belaban Exp $

package org.jgroups;


import org.apache.commons.logging.Log;

import java.io.Serializable;
import java.util.*;


/**
 A channel represents a group communication endpoint (like BSD datagram sockets). A
 client joins a group by connecting the channel to a group address and leaves it by
 disconnecting. Messages sent over the channel are received by all group members that
 are connected to the same group (that is, all members that have the same group
 address).<p>

 The FSM for a channel is roughly as follows: a channel is created
 (<em>unconnected</em>). The channel is connected to a group
 (<em>connected</em>). Messages can now be sent and received. The channel is
 disconnected from the group (<em>unconnected</em>). The channel could now be connected to a
 different group again. The channel is closed (<em>closed</em>).<p>

 Only a single sender is allowed to be connected to a channel at a time, but there can be
 more than one channel in an application.<p>

 Messages can be sent to the group members using the <em>send</em> method and messages
 can be received using <em>receive</em> (pull approach).<p>

 A channel instance is created using either a <em>ChannelFactory</em> or the public
 constructor. Each implementation of a channel must provide a subclass of
 <code>Channel</code> and an implementation of <code>ChannelFactory</code>.  <p>
 Various degrees of sophistication in message exchange can be achieved using building
 blocks on top of channels; e.g., light-weight groups, synchronous message invocation,
 or remote method calls. Channels are on the same abstraction level as sockets, and
 should really be simple to use. Higher-level abstractions are all built on top of
 channels.

 @author  Bela Ban
 @see     java.net.DatagramPacket
 @see     java.net.MulticastSocket
 */
public abstract class Channel implements Transport {
    public static final int BLOCK=0;
    public static final int VIEW=1;
    public static final int SUSPECT=2;
    public static final int LOCAL=3;
    public static final int GET_STATE_EVENTS=4;
    public static final int AUTO_RECONNECT=5;
    public static final int AUTO_GETSTATE=6;


    protected UpHandler          up_handler=null;   // when set, <em>all</em> events are passed to it !
    protected ChannelListener    channel_listener=null;
    protected Set                channel_listeners=null;
    protected Receiver           receiver=null;


    protected abstract Log getLog();

    /**
     Connects the channel to a group. The client is now able to receive group
     messages, views and block events (depending on the options set) and to send
     messages to (all or single) group members.  This is a null operation if already
     connected.<p>

     All channels with the same name form a group, that means all messages
     sent to the group will be received by all channels connected to the same
     channel name.<p>

     @param cluster_name The name of the chanel to connect to.
     @exception ChannelException The protocol stack cannot be started
     @exception ChannelClosedException The channel is closed and therefore cannot be used any longer.
     A new channel has to be created first.
     @see Channel#disconnect
     */
    abstract public void connect(String cluster_name) throws ChannelException, ChannelClosedException;


    /**
     * Connects the channel to a group <em>and</em> fetches the state
     * @param cluster_name
     * @param target
     * @param state_id The ID of a substate. If the full state is to be fetched, set this to null
     * @param timeout
     * @return True if the state could be fetched, otherwise false. If true is returned, the state setting method (e.g.
     * setState() will be called.
     * @throws ChannelException
     */
    abstract public boolean connect(String cluster_name, Address target, String state_id, long timeout) throws ChannelException;


    /** Disconnects the channel from the current group (if connected), leaving the group.
     It is a null operation if not connected. It is a null operation if the channel is closed.

     @see #connect(String) */
    abstract public void disconnect();


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


    /** Shuts down the channel without disconnecting if connected, stops all the threads */
    abstract protected void shutdown();


    /**
     Re-opens a closed channel. Throws an exception if the channel is already open. After this method
     returns, connect() may be called to join a group. The address of this member will be different from
     the previous incarnation.
     */
    public void open() throws ChannelException {
        ;
    }


    /**
     Determines whether the channel is open; 
     i.e., the protocol stack has been created (may not be connected though).
     */
    abstract public boolean isOpen();


    /**
     Determines whether the channel is connected to a group. This implies it is open. If true is returned,
     then the channel can be used to send and receive messages.
     */
    abstract public boolean isConnected();


    /**
     * Returns the number of messages that are waiting. Those messages can be
     * removed by {@link #receive(long)}. Note that this number could change after
     * calling this method and before calling <tt>receive()</tt> (e.g. the latter
     * method might be called by a different thread).
     * @return The number of messages on the queue, or -1 if the queue/channel
     * is closed/disconnected.
     */
    public int getNumMessages() {
        return -1;
    }

    public String dumpQueue() {
        return "";
    }


    /**
     * Returns a map of statistics of the various protocols and of the channel itself.
     * @return Map<String,Map>. A map where the keys are the protocols ("channel" pseudo key is
     * used for the channel itself") and the values are property maps.
     */
    public abstract Map dumpStats();

    /** Sends a message to a (unicast) destination. The message contains
     <ol>
     <li>a destination address (Address). A <code>null</code> address sends the message
     to all group members.
     <li>a source address. Can be left empty. Will be filled in by the protocol stack.
     <li>a byte buffer. The message contents.
     <li>several additional fields. They can be used by application programs (or patterns). E.g.
     a message ID, a <code>oneway</code> field which determines whether a response is
     expected etc.
     </ol>
     @param msg The message to be sent. Destination and buffer should be set. A null destination
     means to send to all group members.

     @exception ChannelNotConnectedException The channel must be connected to send messages.

     @exception ChannelClosedException The channel is closed and therefore cannot be used any longer.
     A new channel has to be created first.

     */
    abstract public void send(Message msg) throws ChannelNotConnectedException, ChannelClosedException;


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


    /**
     Access to event mechanism of channels. Enables to send and receive events, used by building
     blocks to communicate with (building block) specific protocol layers. Currently useful only
     with JChannel.
     */
    public void down(Event evt) {
    }


    /** Receives a message, a view change or a block event. By using <code>setOpt</code>, the
     type of objects to be received can be determined (e.g., not views and blocks, just
     messages).

     The possible types returned can be:
     <ol>
     <li><code>Message</code>. Normal message
     <li><code>Event</code>. All other events (used by JChannel)
     <li><code>View</code>. A view change.
     <li><code>BlockEvent</code>. A block event indicating that a flush protocol has been started, and we should not
     send any more messages. This event should be ack'ed by calling {@link org.jgroups.Channel#blockOk()} .
     Any messages sent after blockOk() returns might get blocked until the flush protocol has completed.
     <li><code>UnblockEvent</code>. An unblock event indicating that the flush protocol has completed and we can resume
     sending messages
     <li><code>SuspectEvent</code>. A notification of a suspected member.
     <li><code>GetStateEvent</code>. The current state of the application should be
     returned using <code>ReturnState</code>.
     <li><code>SetStateEvent</code>. The state of a single/all members as requested previously
     by having called <code>Channel.getState(s).
     <li><code>ExitEvent</code>. Signals that this member was forced to leave the group 
     (e.g., caused by the member being suspected.) The member can rejoin the group by calling
     open(). If the AUTO_RECONNECT is set (see setOpt()), the reconnect will be done automatically.
     </ol>
     The <code>instanceof</code> operator can be used to discriminate between different types
     returned.
     @param timeout Value in milliseconds. Value <= 0 means wait forever
     @return A Message, View, BlockEvent, SuspectEvent, GetStateEvent, SetStateEvent or
     ExitEvent, depending on what is on top of the internal queue.

     @exception ChannelNotConnectedException The channel must be connected to receive messages.

     @exception ChannelClosedException The channel is closed and therefore cannot be used any longer.
     A new channel has to be created first.

     @exception TimeoutException Thrown when a timeout has occurred.
     */
    abstract public Object receive(long timeout) throws ChannelNotConnectedException,
                                                        ChannelClosedException, TimeoutException;


    /** Returns the next message, view, block, suspect or other event <em>without removing
     it from the queue</em>.
     @param timeout Value in milliseconds. Value <= 0 means wait forever
     @return A Message, View, BlockEvent, SuspectEvent, GetStateEvent or SetStateEvent object,
     depending on what is on top of the internal queue.

     @exception ChannelNotConnectedException The channel must be connected to receive messages.

     @exception ChannelClosedException The channel is closed and therefore cannot be used any longer.
     A new channel has to be created first.

     @exception TimeoutException Thrown when a timeout has occurred.

     @see #receive(long)
     */
    abstract public Object peek(long timeout) throws ChannelNotConnectedException, ChannelClosedException, TimeoutException;


    /**
     * Gets the current view. This does <em>not</em> retrieve a new view, use
     <code>receive()</code> to do so. The view may only be available after a successful
     <code>connect()</code>. The result of calling this method on an unconnected channel
     is implementation defined (may return null). Calling it on a channel that is not
     enabled to receive view events (via <code>setOpt</code>) returns
     <code>null</code>. Calling this method on a closed channel returns a null view.
     @return The current view.