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).
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.
AUTO_GETSTATE
public static final int AUTO_GETSTATE
AUTO_RECONNECT
public static final int AUTO_RECONNECT
BLOCK
public static final int BLOCK
GET_STATE_EVENTS
public static final int GET_STATE_EVENTS
LOCAL
public static final int LOCAL
SUSPECT
public static final int SUSPECT
VIEW
public static final int VIEW
channel_listeners
protected Set channel_listeners
addChannelListener
public void addChannelListener(ChannelListener 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.
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.
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.
connect
public abstract void connect(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.
channel_name
- The name of the chanel to connect to.
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.
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.
dumpQueue
public String dumpQueue()
dumpStats
public abstract Map dumpStats()
Returns a map of statistics of the various protocols and of the channel itself.
- Map. A map where the keys are the protocols ("channel" pseudo key is
used for the channel itself") and the values are property maps.
getAllStates
public abstract boolean getAllStates(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
.
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).
- boolean True if the state was retrieved successfully, otherwise false.
getChannelName
public abstract 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
.
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.
- The channel's address. Generated by the underlying transport, and opaque.
Addresses can be used as destination in the
Send
operation.
getLog
protected abstract Log getLog()
getNumMessages
public int getNumMessages()
Returns the number of messages that are waiting. Those messages can be
removed by
receive(long)
. Note that this number could change after
calling this method and before calling
receive() (e.g. the latter
method might be called by a different thread).
- The number of messages on the queue, or -1 if the queue/channel
is closed/disconnected.
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
.
option
- The option to be returned.
- The object associated with an option.
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()
.
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).
- boolean True if the state was retrieved successfully, otherwise false.
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.
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.
isOpen
public abstract boolean isOpen()
Determines whether the channel is open;
i.e., the protocol stack has been created (may not be connected though).
notifyChannelClosed
protected void notifyChannelClosed(Channel c)
notifyChannelConnected
protected void notifyChannelConnected(Channel c)
notifyChannelDisconnected
protected void notifyChannelDisconnected(Channel c)
notifyChannelReconnected
protected void notifyChannelReconnected(Address addr)
notifyChannelShunned
protected void notifyChannelShunned()
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.
option2String
public static String option2String(int option)
peek
public abstract Object peek(long timeout)
throws ChannelNotConnectedException,
ChannelClosedException,
TimeoutException
Returns the next message, view, block, suspect or other event without removing
it from the queue.
timeout
- Value in milliseconds. Value <= 0 means wait forever
- A Message, View, BlockEvent, SuspectEvent, GetStateEvent or SetStateEvent object,
depending on what is on top of the internal queue.
receive
public abstract 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:
Message
. Normal message
Event
. All other events (used by JChannel)
View
. A view change.
BlockEvent
. A block event indicating an impending view change.
SuspectEvent
. A notification of a suspected member.
GetStateEvent
. The current state of the application should be
returned using ReturnState
.
SetStateEvent
. The state of a single/all members as requested previously
by having called Channel.getState(s).
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.
- receive in interface Transport
timeout
- Value in milliseconds. Value <= 0 means wait forever
- A Message, View, BlockEvent, SuspectEvent, GetStateEvent, SetStateEvent or
ExitEvent, depending on what is on top of the internal queue.
removeChannelListener
public void removeChannelListener(ChannelListener listener)
returnState
public abstract void returnState(byte[] state)
Called by the application is response to receiving a
getState()
object when calling receive()
.
state
- The state of the application as a byte buffer
(to send over the network).
send
public abstract void send(Address dst,
Address src,
Serializable obj)
throws ChannelNotConnectedException,
ChannelClosedException
Helper method. Will create a Message(dst, src, obj) and use send(Message).
dst
- Destination address for message. If null, message will be sent to all current group memberssrc
- 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.
send
public abstract void send(Message msg)
throws ChannelNotConnectedException,
ChannelClosedException
Sends a message to a (unicast) destination. The message contains
- a destination address (Address). A
null
address sends the message
to all group members.
- a source address. Can be left empty. Will be filled in by the protocol stack.
- a byte buffer. The message contents.
- 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.
- send in interface Transport
msg
- The message to be sent. Destination and buffer should be set. A null destination
means to send to all group members.
setChannelListener
public void setChannelListener(ChannelListener channel_listener)
Use addChannelListener() instead
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,
Object value)
Sets an option. The following options are currently recognized:
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.
VIEW
. Turn the reception of VIEW events on/off (value is Boolean).
Default is on.
SUSPECT
. Turn the reception of SUSPECT events on/off (value is Boolean).
Default is on.
LOCAL
. Receive its own broadcast messages to the group
(value is Boolean). Default is on.
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).
AUTO_RECONNECT
. Turn auto-reconnection on/off. If on, when a member if forced out
of a group (EXIT event), then we will reconnect.
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.
setReceiver
public void setReceiver(Receiver r)
Sets the receiver, which will handle all messages, view changes etc
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.