org.javagroups
Class Channel

java.lang.Object
  extended byorg.javagroups.Channel
All Implemented Interfaces:
Transport
Direct Known Subclasses:
EnsChannel, JChannel

public abstract class Channel
extends java.lang.Object
implements Transport

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 member that have the same group address).

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

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.

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

A channel instance is created using either a ChannelFactory or the public constructor. Each implementation of a channel must provide a subclass of Channel and an implementation of ChannelFactory.

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 Also:
DatagramPacket, MulticastSocket

Field Summary
static int AUTO_GETSTATE
           
static int AUTO_RECONNECT
           
static int BLOCK
           
protected  ChannelListener channel_listener
           
static int GET_STATE_EVENTS
           
static int LOCAL
           
static int SUSPECT
           
protected  UpHandler up_handler
           
static int VIEW
           
 
Constructor Summary
protected Channel()
          Hidden from clients
protected Channel(java.lang.Object properties)
          Creates a channel (initially not connected).
 
Method Summary
abstract  void blockOk()
          Called to acknowledge a Block (callback in MembershipListener or BlockEvent received from call to Receive).
abstract  void close()
          Destroys the channel and its associated resources (e.g.
abstract  void connect(java.lang.String channel_name)
          Connects the channel to a group.
abstract  void disconnect()
          Disconnects the channel from the current group (if connected), leaving the group.
 void down(Event evt)
          Access to event mechanism of channels.
abstract  boolean getAllStates(java.util.Vector targets, long timeout)
          Retrieve all states of the group members.
abstract  java.lang.String getChannelName()
          Returns the group address of the group of which the channel is a member.
abstract  Address getLocalAddress()
          Returns the channel's own address.
abstract  java.lang.Object getOpt(int option)
          Gets an option.
abstract  boolean getState(Address target, long timeout)
          Retrieve the state of the group.
abstract  View getView()
          Gets the current view.
abstract  boolean isConnected()
          Determines whether the channel is connected to a group.
abstract  boolean isOpen()
          Determines whether the channel is open, ie.
 void open()
          Re-opens a closed channel.
static java.lang.String option2String(int option)
           
abstract  java.lang.Object peek(long timeout)
          Returns the next message, view, block, suspect or other event without removing it from the queue.
abstract  java.lang.Object receive(long timeout)
          Receives a message, a view change or a block event.
abstract  void returnState(byte[] state)
          Called by the application is response to receiving a getState() object when calling receive().
abstract  void send(Address dst, Address src, java.io.Serializable obj)
          Helper method.
abstract  void send(Message msg)
          Sends a message to a (unicast) destination.
 void setChannelListener(ChannelListener channel_listener)
          Allows to be notified when a channel event such as connect, disconnect or close occurs.
abstract  void setOpt(int option, java.lang.Object value)
          Sets an option.
 void setUpHandler(UpHandler up_handler)
          When up_handler is set, all events will be passed to it directly.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BLOCK

public static final int BLOCK
See Also:
Constant Field Values

VIEW

public static final int VIEW
See Also:
Constant Field Values

SUSPECT

public static final int SUSPECT
See Also:
Constant Field Values

LOCAL

public static final int LOCAL
See Also:
Constant Field Values

GET_STATE_EVENTS

public static final int GET_STATE_EVENTS
See Also:
Constant Field Values

AUTO_RECONNECT

public static final int AUTO_RECONNECT
See Also:
Constant Field Values

AUTO_GETSTATE

public static final int AUTO_GETSTATE
See Also:
Constant Field Values

up_handler

protected UpHandler up_handler

channel_listener

protected ChannelListener channel_listener
Constructor Detail

Channel

protected Channel()
           throws ChannelException
Hidden from clients


Channel

protected Channel(java.lang.Object properties)
           throws ChannelException
Creates a channel (initially not connected).

Parameters:
properties - Properties of the channel. This argument serves a generic option (hint) for subclasses as to how to create the channel (parameterization). Interpreted by the channel subclasses. May be for example a String denoting the QoS required by the underlying transport, or null to use default properties.
Throws:
ChannelException - Channel creation failed.
Method Detail

connect

public abstract void connect(java.lang.String channel_name)
                      throws ChannelException,
                             ChannelClosedException
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.

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.

Parameters:
channel_name - The name of the chanel to connect to.
Throws:
ChannelException - The protocol stack cannot be started
ChannelClosedException - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
See Also:
Channel.disconnect

disconnect

public abstract void disconnect()
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 Also:
Channel.connect

close

public abstract void close()
Destroys the channel and its associated resources (e.g. the protocol stack). After a channel has been closed, invoking methods on it throws the ChannelClosed exception (or results in a null operation). It is a null operation if the channel is already closed.

If the channel is connected to a group, disconnec()t will be called first.


open

public void open()
          throws ChannelException
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.

Throws:
ChannelException

isOpen

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


isConnected

public abstract boolean isConnected()
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.


send

public abstract void send(Message msg)
                   throws ChannelNotConnectedException,
                          ChannelClosedException
Sends a message to a (unicast) destination. The message contains
  1. a destination address (Address). A null address sends the message to all group members.
  2. a source address. Can be left empty. Will be filled in by the protocol stack.
  3. a byte buffer. The message contents.
  4. several additional fields. They can be used by application programs (or patterns). E.g. a message ID, a oneway field which determines whether a response is expected etc.

Specified by:
send in interface Transport
Parameters:
msg - The message to be sent. Destination and buffer should be set. A null destination means to send to all group members.
Throws:
ChannelNotConnected - The channel must be connected to send messages.
ChannelClosed - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
ChannelNotConnectedException
ChannelClosedException

send

public abstract void send(Address dst,
                          Address src,
                          java.io.Serializable obj)
                   throws ChannelNotConnectedException,
                          ChannelClosedException
Helper method. Will create a Message(dst, src, obj) and use send(Message).

Parameters:
dst - Destination address for message. If null, message will be sent to all current group members
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.
obj - Serializable object. Will be serialized into the byte buffer of the Message. If it is not serializable, the byte buffer will be null.
Throws:
ChannelNotConnectedException
ChannelClosedException

down

public void down(Event evt)
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.


receive

public abstract java.lang.Object receive(long timeout)
                                  throws ChannelNotConnectedException,
                                         ChannelClosedException,
                                         TimeoutException
Receives a message, a view change or a block event. By using setOpt, the type of objects to be received can be determined (e.g. not views and blocks, just messages). The possible types returned can be:
  1. Message. Normal message
  2. Event. All other events (used by JChannel)
  3. View. A view change.
  4. BlockEvent. A block event indicating an impending view change.
  5. SuspectEvent. A notification of a suspected member.
  6. GetStateEvent. The current state of the application should be returned using ReturnState.
  7. SetStateEvent. The state of a single/all members as requested previously by having called Channel.getState(s).
  8. ExitEvent. 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.
The instanceof operator can be used to discriminate between different types returned.

Specified by:
receive in interface Transport
Parameters:
timeout - Value in milliseconds. Value <= 0 means wait forever
Returns:
A Message, View, BlockEvent, SuspectEvent, GetStateEvent, SetStateEvent or ExitEvent, depending on what is on top of the internal queue.
Throws:
ChannelNotConnected - The channel must be connected to receive messages.
ChannelClosed - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
TimeoutException - Thrown when a timeout has occurred.
ChannelNotConnectedException
ChannelClosedException

peek

public abstract java.lang.Object peek(long timeout)
                               throws ChannelNotConnectedException,
                                      ChannelClosedException,
                                      TimeoutException
Returns the next message, view, block, suspect or other event without removing it from the queue.

Parameters:
timeout - Value in milliseconds. Value <= 0 means wait forever
Returns:
A Message, View, BlockEvent, SuspectEvent, GetStateEvent or SetStateEvent object, depending on what is on top of the internal queue.
Throws:
ChannelNotConnected - The channel must be connected to receive messages.
ChannelClosed - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
TimeoutException - Thrown when a timeout has occurred.
ChannelNotConnectedException
ChannelClosedException
See Also:
Receive

getView

public abstract View getView()
Gets the current view. This does not retrieve a new view, use Receive to do so. The view may only be available after a successful Connect. 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 setOpt) returns null. Calling this method on a closed channel returns a null view.

Returns:
The current view.

getLocalAddress

public abstract Address getLocalAddress()
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.

Returns:
The channel's address. Generated by the underlying transport, and opaque. Addresses can be used as destination in the Send operation.

getChannelName

public abstract java.lang.String getChannelName()
Returns the group address of the group of which the channel is a member. This is the object that was the argument to Connect. Calling this method on a closed channel returns null.

Returns:
The group address

setUpHandler

public void setUpHandler(UpHandler up_handler)
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.


setChannelListener

public void setChannelListener(ChannelListener 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.


setOpt

public abstract void setOpt(int option,
                            java.lang.Object value)
Sets an option. The following options are currently recognized:
  1. BLOCK. Turn the reception of BLOCK events on/off (value is Boolean). Default is off. If set to on, receiving VIEW events will be set to on, too.
  2. VIEW. Turn the reception of VIEW events on/off (value is Boolean). Default is on.
  3. SUSPECT. Turn the reception of SUSPECT events on/off (value is Boolean). Default is on.
  4. LOCAL. Receive its own broadcast messages to the group (value is Boolean). Default is on.
  5. GET_STATE_EVENTS. Turn the reception of GetState events on/off (value is Boolean). Default is off, which means that no other members can ask this member for its state (null will be returned).
  6. AUTO_RECONNECT. Turn auto-reconnection on/off. If on, when a member if forced out of a group (EXIT event), then we will reconnect.
  7. AUTO_GETSTATE. Turn automatic fetching of state after an auto-reconnect on/off. This also sets AUTO_RECONNECT to true (if not yet set).
This method can be called on an unconnected channel. Calling this method on a closed channel has no effect.


getOpt

public abstract java.lang.Object getOpt(int option)
Gets an option. This method can be called on an unconnected channel. Calling this method on a closed channel returns null.

Parameters:
option - The option to be returned.
Returns:
The object associated with an option.

blockOk

public abstract void blockOk()
Called to acknowledge a Block (callback in MembershipListener or BlockEvent received from call to Receive). 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.


getState

public abstract boolean getState(Address target,
                                 long timeout)
                          throws ChannelNotConnectedException,
                                 ChannelClosedException
Retrieve the state of the group. Will usually contact the oldest group member to get the state. When the method returns true, a SetStateEvent will have been added to the channel's queue, causing receive() to return the state in one of the next invocations. If false, no state will be retrieved by receive().

Parameters:
target - The address of the member from which the state is to be retrieved. If it is null, the coordinator is contacted.
timeout - Milliseconds to wait for the response (0 = wait indefinitely).
Returns:
boolean True if the state was retrieved successfully, otherwise false.
Throws:
ChannelNotConnected - The channel must be connected to receive messages.
ChannelClosed - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
ChannelNotConnectedException
ChannelClosedException

getAllStates

public abstract boolean getAllStates(java.util.Vector targets,
                                     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 SetStateEvent will have been added to the channel's queue, causing Receive to return the states in one of the next invocations. If false, no states will be retrieved by Receive.

Parameters:
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.
timeout - Milliseconds to wait for the response (0 = wait indefinitely).
Returns:
boolean True if the state was retrieved successfully, otherwise false.
Throws:
ChannelNotConnected - The channel must be connected to receive messages.
ChannelClosed - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
ChannelNotConnectedException
ChannelClosedException

returnState

public abstract void returnState(byte[] state)
Called by the application is response to receiving a getState() object when calling receive().

Parameters:
state - The state of the application as a byte buffer (to send over the network).

option2String

public static java.lang.String option2String(int option)


Copyright © 2001,2002 www.javagroups.com . All Rights Reserved.