All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class JavaGroups.Channel 

java.lang.Object
   |
   +----JavaGroups.Channel
public abstract class Channel
extends 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

Variable Index

o BLOCK
o LOCAL
o SUSPECT
o VIEW

Method Index

o BlockOk()
Called to acknowledge a Block (callback in MembershipListener).
o Close()
Destroys the channel and its associated resources (e.g.
o Connect(Object)
Connects the channel to a group.
o Disconnect()
Disconnects the channel from the current group (if connected), leaving the group.
o GetGroupAddress()
Returns the group address of the group of which the channel is a member.
o GetLocalAddress()
Returns the channel's own address.
o GetOpt(int)
Gets an option.
o GetView()
Gets the current view.
o Peek(long)
Returns the next message, view, block or suspect event without removing it from the queue.
o Receive(long)
Receives a message, a view change or a block event.
o Send(Message)
Sends a message to a destination.
o SetOpt(int, Object)
Sets an option.

Variables

o BLOCK 
 public static final int BLOCK
o VIEW 
 public static final int VIEW
o SUSPECT 
 public static final int SUSPECT
o LOCAL 
 public static final int LOCAL

Methods

o Connect 
 public abstract void Connect(Object group_address) throws ChannelClosed
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 group address form a group, that means all messages sent to the group will be received by all channels connected to the same group address.

The group address is opaque, and can only be interpreted by a channel implementation, i.e. the implementation decides what to do with the object.

Throws: ChannelClosed
The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
See Also:
Disconnect
o 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:
Connect
o 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, Disconnect will be called first.

o Send 
 public abstract void Send(Message msg) throws ChannelNotConnected, ChannelClosed
Sends a message to a destination. The message contains
  1. a destination address (Object). 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.

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.
Throws: ChannelClosed
The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
o Receive 
 public abstract Object Receive(long timeout) throws ChannelNotConnected, ChannelClosed, Timeout
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. View. A view change.
  3. BlockEvent. A block event indicating an impending view change.
  4. SuspectEvent. A notification of a suspected member.
The instanceof operator can be used to discriminate between different types returned.

Parameters:
timeout - Value in milliseconds. Value <= 0 means wait forever
Returns:
A Message, View, BlockEvent or SuspectEvent object, depending on what is on top of the internal queue.
Throws: ChannelNotConnected
The channel must be connected to receive messages.
Throws: ChannelClosed
The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
Throws: Timeout
Thrown when a timeout has occurred.
o Peek 
 public abstract Object Peek(long timeout) throws ChannelNotConnected, ChannelClosed, Timeout
Returns the next message, view, block or suspect event without removing it from the queue.

Parameters:
timeout - Value in milliseconds. Value <= 0 means wait forever
Returns:
A Message, View, BlockEvent or SuspectEvent object, depending on what is on top of the internal queue.
Throws: ChannelNotConnected
The channel must be connected to receive messages.
Throws: ChannelClosed
The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
Throws: Timeout
Thrown when a timeout has occurred.
See Also:
Receive
o 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.
o GetLocalAddress 
 public abstract Object 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.
o GetGroupAddress 
 public abstract Object GetGroupAddress()
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
o SetOpt 
 public abstract void SetOpt(int option,
                             Object value)
Sets an option. The following options are currently recognized:
  1. BLOCK (0). 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 (1). Turn the reception of VIEW events on/off (value is Boolean). Default is on.
  3. SUSPECT (2). Turn the reception of SUSPECT events on/off (value is Boolean). Default is on.
  4. LOCAL (3). Receive its own broadcast messages to the group (value is Boolean). Default is on.
This method can be called on an unconnected channel. Calling this method on a closed channel has no effect.

o GetOpt 
 public abstract 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.
o BlockOk 
 public abstract void BlockOk()
Called to acknowledge a Block (callback in MembershipListener). 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. 

All Packages  Class Hierarchy  This Package  Previous  Next  Index