|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.javagroups.Channel
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.
DatagramPacket
,
java.net.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. |
void |
returnState(java.lang.Object 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 |
public static final int BLOCK
public static final int VIEW
public static final int SUSPECT
public static final int LOCAL
public static final int GET_STATE_EVENTS
public static final int AUTO_RECONNECT
public static final int AUTO_GETSTATE
protected UpHandler up_handler
protected ChannelListener channel_listener
Constructor Detail |
protected Channel() throws ChannelException
protected Channel(java.lang.Object properties) throws ChannelException
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.ChannelException
- Channel creation failed.Method Detail |
public abstract void connect(java.lang.String channel_name) throws ChannelClosedException
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.ChannelClosed
- The channel is closed and therefore cannot be used any longer.
A new channel has to be created first.Channel.disconnect
public abstract void disconnect()
Channel.connect
public abstract void close()
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.
public void open() throws ChannelException
public abstract boolean isOpen()
public abstract boolean isConnected()
public abstract void send(Message msg) throws ChannelNotConnectedException, ChannelClosedException
null
address sends the message
to all group members.
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.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.public abstract void send(Address dst, Address src, java.io.Serializable obj) throws ChannelNotConnectedException, ChannelClosedException
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.public void down(Event evt)
public abstract java.lang.Object receive(long timeout) throws ChannelNotConnectedException, ChannelClosedException, TimeoutException
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.
instanceof
operator can be used to discriminate between different types
returned.receive
in interface Transport
timeout
- Value in milliseconds. Value <= 0 means wait foreverChannelNotConnected
- 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.public abstract java.lang.Object peek(long timeout) throws ChannelNotConnectedException, ChannelClosedException, TimeoutException
timeout
- Value in milliseconds. Value <= 0 means wait foreverChannelNotConnected
- 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.Receive
public abstract View getView()
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.public abstract Address getLocalAddress()
Send
operation.public abstract java.lang.String getChannelName()
Connect
. Calling this method on a closed
channel returns null
.public void setUpHandler(UpHandler up_handler)
public void setChannelListener(ChannelListener channel_listener)
public abstract void setOpt(int option, java.lang.Object value)
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).
public abstract java.lang.Object getOpt(int option)
null
.option
- The option to be returned.public abstract void blockOk()
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.public abstract boolean getState(Address target, long timeout)
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).public abstract boolean getAllStates(java.util.Vector targets, long timeout)
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).public void returnState(java.lang.Object state)
GetState
object when
calling Receive
.state
- The state of the application as a Serializable or Externaizable
(to send over the network).public static java.lang.String option2String(int option)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |