channel.java

JGRoups源码

     */
    abstract public View getView();


    /**
     Returns the channel's own address. The result of calling this method on an unconnected
     channel is implementation defined (may return null). Calling this method on a closed
     channel returns null.

     @return The channel's address. Generated by the underlying transport, and opaque.
     Addresses can be used as destination in the <code>Send</code> operation.
     */
    abstract public Address getLocalAddress();


    /**
     Returns the group address of the group of which the channel is a member. This is
     the object that was the argument to <code>connect()</code>. Calling this method on a closed
     channel returns <code>null</code>.
     @return The group address
     @deprecated Use {@link #getClusterName()} instead */
    abstract public String getChannelName();

    /**
     Returns the cluster name of the group of which the channel is a member. This is
     the object that was the argument to <code>connect()</code>. Calling this method on a closed
     channel returns <code>null</code>.
     @return The cluster name */
    abstract public String getClusterName();


    /**
     When up_handler is set, all events will be passed to it directly. These will not be received
     by the channel (except connect/disconnect, state retrieval and the like). This can be used by
     building blocks on top of a channel; thus the channel is used as a pass-through medium, and
     the building blocks take over some of the channel's tasks. However, tasks such as connection
     management and state transfer is still handled by the channel.
     */
    public void setUpHandler(UpHandler up_handler) {
        this.up_handler=up_handler;
    }


    /**
     Allows to be notified when a channel event such as connect, disconnect or close occurs.
     E.g. a PullPushAdapter may choose to stop when the channel is closed, or to start when
     it is opened.
     @deprecated Use addChannelListener() instead
     */
    public void setChannelListener(ChannelListener channel_listener) {
        addChannelListener(channel_listener);
    }

    /**
     Allows to be notified when a channel event such as connect, disconnect or close occurs.
     E.g. a PullPushAdapter may choose to stop when the channel is closed, or to start when
     it is opened.
     */
    public synchronized void addChannelListener(ChannelListener listener) {
        if(listener == null)
            return;
        if(channel_listeners == null)
            channel_listeners=new LinkedHashSet();
        channel_listeners.add(listener);
    }

    public synchronized void removeChannelListener(ChannelListener listener) {
        if(channel_listeners != null)
            channel_listeners.remove(listener);
    }

    /** Sets the receiver, which will handle all messages, view changes etc */
    public void setReceiver(Receiver r) {
        receiver=r;
    }

    /**
     Sets an option. The following options are currently recognized:
     <ol>
     <li><code>BLOCK</code>. Turn the reception of BLOCK events on/off (value is Boolean).
     Default is off
     <li><code>LOCAL</code>. Receive its own broadcast messages to the group
     (value is Boolean). Default is on.
     <li><code>AUTO_RECONNECT</code>. Turn auto-reconnection on/off. If on, when a member if forced out
     of a group (EXIT event), then we will reconnect.
     <li><code>AUTO_GETSTATE</code>. Turn automatic fetching of state after an auto-reconnect on/off.
     This also sets AUTO_RECONNECT to true (if not yet set).
     </ol>
     This method can be called on an unconnected channel. Calling this method on a
     closed channel has no effect.
     */
    abstract public void setOpt(int option, Object value);


    /**
     Gets an option. This method can be called on an unconnected channel.  Calling this
     method on a closed channel returns <code>null</code>.

     @param option  The option to be returned.
     @return The object associated with an option.
     */
    abstract public Object getOpt(int option);

    abstract public boolean flushSupported();

    abstract public boolean startFlush(long timeout, boolean automatic_resume);

    abstract public void stopFlush();


    /** Called to acknowledge a block() (callback in <code>MembershipListener</code> or
     <code>BlockEvent</code> received from call to <code>Receive</code>).
     After sending BlockOk, no messages should be sent until a new view has been received.
     Calling this method on a closed channel has no effect.
     */
    abstract public void blockOk();


    /**
     Retrieve the state of the group. Will usually contact the oldest group member to get
     the state. When the method returns true, a <code>SetStateEvent</code> will have been
     added to the channel's queue, causing <code>receive()</code> to return the state in one of
     the next invocations. If false, no state will be retrieved by <code>receive()</code>.
     @param target The address of the member from which the state is to be retrieved. If it is
     null, the coordinator is contacted.
     @param timeout Milliseconds to wait for the response (0 = wait indefinitely).
     @return boolean True if the state was retrieved successfully, otherwise false.
     @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.

     */
    abstract public boolean getState(Address target, long timeout)
            throws ChannelNotConnectedException, ChannelClosedException;


    /**
     * Fetches a partial state identified by state_id.
     * @param target
     * @param state_id
     * @param timeout
     * @return
     * @throws ChannelNotConnectedException
     * @throws ChannelClosedException
     */
    abstract public boolean getState(Address target, String state_id, long timeout)
            throws ChannelNotConnectedException, ChannelClosedException;

    /**
     Retrieve all states of the group members. Will contact all group members to get
     the states. When the method returns true, a <code>SetStateEvent</code> will have been
     added to the channel's queue, causing <code>Receive</code> to return the states in one of
     the next invocations. If false, no states will be retrieved by <code>Receive</code>.
     @param targets A list of members which are contacted for states. If the list is null,
     all the current members of the group will be contacted.
     @param timeout Milliseconds to wait for the response (0 = wait indefinitely).
     @return boolean True if the state was retrieved successfully, otherwise false.
     @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.
     @deprecated Not really needed - we always want to get the state from a single member
     */
    abstract public boolean getAllStates(Vector targets, long timeout)
            throws ChannelNotConnectedException, ChannelClosedException;


    /**
     * Called by the application is response to receiving a
     * <code>getState()</code> object when calling <code>receive()</code>.
     * @param state The state of the application as a byte buffer
     *              (to send over the network).
     */
    public abstract void returnState(byte[] state);

    /** Returns a given substate (state_id of null means return entire state) */
    public abstract void returnState(byte[] state, String state_id);


    public static String option2String(int option) {
        switch(option) {
            case BLOCK:
                return "BLOCK";
            case VIEW:
                return "VIEW";
            case SUSPECT:
                return "SUSPECT";
            case LOCAL:
                return "LOCAL";
            case GET_STATE_EVENTS:
                return "GET_STATE_EVENTS";
            case AUTO_RECONNECT:
                return "AUTO_RECONNECT";
            case AUTO_GETSTATE:
                return "AUTO_GETSTATE";
            default:
                return "unknown (" + option + ')';
        }
    }

    protected void notifyChannelConnected(Channel c) {
        if(channel_listeners == null) return;
        for(Iterator it=channel_listeners.iterator(); it.hasNext();) {
            ChannelListener channelListener=(ChannelListener)it.next();
            try {
                channelListener.channelConnected(c);
            }
            catch(Throwable t) {
                getLog().error("exception in channelConnected() callback", t);
            }
        }
    }

    protected void notifyChannelDisconnected(Channel c) {
        if(channel_listeners == null) return;
        for(Iterator it=channel_listeners.iterator(); it.hasNext();) {
            ChannelListener channelListener=(ChannelListener)it.next();
            try {
                channelListener.channelDisconnected(c);
            }
            catch(Throwable t) {
                getLog().error("exception in channelDisonnected() callback", t);
            }
        }
    }

    protected void notifyChannelClosed(Channel c) {
        if(channel_listeners == null) return;
        for(Iterator it=channel_listeners.iterator(); it.hasNext();) {
            ChannelListener channelListener=(ChannelListener)it.next();
            try {
                channelListener.channelClosed(c);
            }
            catch(Throwable t) {
                getLog().error("exception in channelClosed() callback", t);
            }
        }
    }

    protected void notifyChannelShunned() {
        if(channel_listeners == null) return;
        for(Iterator it=channel_listeners.iterator(); it.hasNext();) {
            ChannelListener channelListener=(ChannelListener)it.next();
            try {
                channelListener.channelShunned();
            }
            catch(Throwable t) {
                getLog().error("exception in channelShunned() callback", t);
            }
        }
    }

    protected void notifyChannelReconnected(Address addr) {
        if(channel_listeners == null) return;
        for(Iterator it=channel_listeners.iterator(); it.hasNext();) {
            ChannelListener channelListener=(ChannelListener)it.next();
            try {
                channelListener.channelReconnected(addr);
            }
            catch(Throwable t) {
                getLog().error("exception in channelReconnected() callback", t);
            }
        }
    }


}