public abstract class Channel extends Object implements Transport
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
,
MulticastSocket
Modifier and Type | Field and Description |
---|---|
static int |
AUTO_GETSTATE
Deprecated.
|
static int |
AUTO_RECONNECT
Deprecated.
|
static int |
BLOCK
Deprecated.
|
protected Set<ChannelListener> |
channel_listeners |
static int |
GET_STATE_EVENTS
Deprecated.
|
static int |
LOCAL |
protected Receiver |
receiver |
protected SocketFactory |
socket_factory |
static int |
SUSPECT
Deprecated.
|
protected UpHandler |
up_handler |
static int |
VIEW
Deprecated.
|
Constructor and Description |
---|
Channel() |
Modifier and Type | Method and Description |
---|---|
void |
addChannelListener(ChannelListener listener)
Allows to be notified when a channel event such as connect, disconnect or close occurs.
|
abstract void |
blockOk()
Called to acknowledge a block() (callback in
MembershipListener or
BlockEvent received from call to Receive ). |
void |
clearChannelListeners() |
abstract void |
close()
Destroys the channel and its associated resources (e.g., the protocol stack).
|
abstract void |
connect(String cluster_name)
Connects the channel to a group.
|
abstract void |
connect(String cluster_name,
Address target,
String state_id,
long timeout)
Connects the channel to a group and fetches the state
|
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.
|
Object |
downcall(Event evt)
Can be used instead of down() when a return value is expected.
|
String |
dumpQueue() |
abstract Map<String,Object> |
dumpStats()
Returns a map of statistics of the various protocols and of the channel itself.
|
abstract boolean |
flushSupported() |
abstract Address |
getAddress()
Returns the channel's own address.
|
abstract boolean |
getAllStates(Vector targets,
long timeout)
Deprecated.
Not really needed - we always want to get the state from a single member
|
abstract String |
getChannelName()
Deprecated.
Use
getClusterName() instead |
abstract String |
getClusterName()
Returns the cluster name of the group of which the channel is a member.
|
abstract Map<String,Object> |
getInfo() |
abstract Address |
getLocalAddress()
Deprecated.
Use
getAddress() instead |
protected abstract Log |
getLog() |
abstract String |
getName()
Returns the logical name of this channel if set.
|
abstract String |
getName(Address member)
Returns the logical name of a given member.
|
int |
getNumMessages()
Returns the number of messages that are waiting.
|
abstract Object |
getOpt(int option)
Gets an option.
|
String |
getProperties() |
abstract ProtocolStack |
getProtocolStack() |
Receiver |
getReceiver() |
SocketFactory |
getSocketFactory() |
abstract boolean |
getState(Address target,
long timeout)
Retrieve the state of the group.
|
abstract boolean |
getState(Address target,
String state_id,
long timeout)
Fetches a partial state identified by state_id.
|
UpHandler |
getUpHandler() |
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;
i.e., the protocol stack has been created (may not be connected though).
|
protected void |
notifyChannelClosed(Channel c) |
protected void |
notifyChannelConnected(Channel c) |
protected void |
notifyChannelDisconnected(Channel c) |
void |
open()
Re-opens a closed channel.
|
static String |
option2String(int option) |
abstract Object |
peek(long timeout)
Deprecated.
Use a
Receiver instead, this method will not be available in JGroups 3.0 |
abstract Object |
receive(long timeout)
Deprecated.
Use a
Receiver instead |
void |
removeChannelListener(ChannelListener listener) |
abstract void |
returnState(byte[] state)
Called by the application is response to receiving a
getState() object when calling receive() . |
abstract void |
returnState(byte[] state,
String state_id)
Returns a given substate (state_id of null means return entire state)
|
abstract void |
send(Address dst,
Address src,
byte[] buf) |
abstract void |
send(Address dst,
Address src,
byte[] buf,
int offset,
int length) |
abstract void |
send(Address dst,
Address src,
Serializable obj)
Helper method.
|
abstract void |
send(Message msg)
Sends a message to a (unicast) destination.
|
void |
setChannelListener(ChannelListener channel_listener)
Deprecated.
Use addChannelListener() instead
|
abstract void |
setInfo(String key,
Object value) |
abstract void |
setName(String name)
Sets the logical name for the channel.
|
abstract void |
setOpt(int option,
Object value)
Sets an option.
|
void |
setReceiver(Receiver r)
Sets the receiver, which will handle all messages, view changes etc
|
void |
setSocketFactory(SocketFactory factory) |
void |
setUpHandler(UpHandler up_handler)
When up_handler is set, all events will be passed to it directly.
|
abstract void |
shutdown()
Deprecated.
|
abstract boolean |
startFlush(boolean automatic_resume) |
abstract boolean |
startFlush(List<Address> flushParticipants,
boolean automatic_resume) |
abstract boolean |
startFlush(long timeout,
boolean automatic_resume) |
abstract void |
stopFlush() |
abstract void |
stopFlush(List<Address> flushParticipants) |
@Deprecated public static final int BLOCK
@Deprecated public static final int VIEW
@Deprecated public static final int SUSPECT
public static final int LOCAL
@Deprecated public static final int GET_STATE_EVENTS
@Deprecated public static final int AUTO_RECONNECT
@Deprecated public static final int AUTO_GETSTATE
protected UpHandler up_handler
protected Set<ChannelListener> channel_listeners
protected Receiver receiver
protected SocketFactory socket_factory
protected abstract Log getLog()
public abstract ProtocolStack getProtocolStack()
public SocketFactory getSocketFactory()
public void setSocketFactory(SocketFactory factory)
public abstract void connect(String cluster_name) throws ChannelException
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.
cluster_name
- The name of the chanel to connect to.ChannelException
- The protocol stack cannot be startedChannelClosedException
- The channel is closed and therefore cannot be used any longer.
A new channel has to be created first.disconnect()
public abstract void connect(String cluster_name, Address target, String state_id, long timeout) throws ChannelException
cluster_name
- The name of the cluster to connect to.target
- The address of the member from which the state is to be
retrieved. If it is null, the state is retrieved from coordinator is contacted.state_id
- The ID of a substate. If the full state is to be fetched, set
this parameter to nulltimeout
- Milliseconds to wait for the state response (0 = wait indefinitely).ChannelException
- thrown if connecting to cluster was not successfulStateTransferException
- thrown if state transfer was not successfulpublic abstract void disconnect()
connect(String)
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, disconnec()t
will be called first.
@Deprecated public abstract void shutdown()
public void open() throws ChannelException
ChannelException
public abstract boolean isOpen()
public abstract boolean isConnected()
public int getNumMessages()
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).public String dumpQueue()
public abstract Map<String,Object> dumpStats()
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.ChannelNotConnectedException
- The channel must be connected to send messages.ChannelClosedException
- 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, 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.ChannelNotConnectedException
ChannelClosedException
public abstract void send(Address dst, Address src, byte[] buf) throws ChannelNotConnectedException, ChannelClosedException
public abstract void send(Address dst, Address src, byte[] buf, int offset, int length) throws ChannelNotConnectedException, ChannelClosedException
public void down(Event evt)
public Object downcall(Event evt)
evt
- public abstract Object receive(long timeout) throws ChannelNotConnectedException, ChannelClosedException, TimeoutException
Receiver
insteadsetOpt
, 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 that a flush protocol has been started, and we should not
send any more messages. This event should be ack'ed by calling blockOk()
.
Any messages sent after blockOk() returns might get blocked until the flush protocol has completed.
UnblockEvent
. An unblock event indicating that the flush protocol has completed and we can resume
sending messages
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 foreverChannelNotConnectedException
- The channel must be connected to receive messages.ChannelClosedException
- 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 Object peek(long timeout) throws ChannelNotConnectedException, ChannelClosedException, TimeoutException
Receiver
instead, this method will not be available in JGroups 3.0timeout
- Value in milliseconds. Value <= 0 means wait foreverChannelNotConnectedException
- The channel must be connected to receive messages.ChannelClosedException
- 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(long)
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()
getAddress()
insteadsend()
operation.public abstract Address getAddress()
getAddress()
. Addresses can be used as destination
in the send()
operation.public abstract String getName()
public abstract String getName(Address member)
member
- public abstract void setName(String name)
name
- public abstract String getChannelName()
getClusterName()
insteadconnect()
. Calling this method on a closed
channel returns null
.public abstract String getClusterName()
connect()
. Calling this method on a closed
channel returns null
.public String getProperties()
public void setUpHandler(UpHandler up_handler)
public UpHandler getUpHandler()
public void setChannelListener(ChannelListener channel_listener)
public void addChannelListener(ChannelListener listener)
public void removeChannelListener(ChannelListener listener)
public void clearChannelListeners()
public void setReceiver(Receiver r)
public Receiver getReceiver()
public abstract void setOpt(int option, Object value)
BLOCK
. Turn the reception of BLOCK events on/off (value is Boolean).
Default is off
LOCAL
. Receive its own broadcast messages to the group
(value is Boolean). Default is on.
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 Object getOpt(int option)
null
.option
- The option to be returned.public abstract boolean flushSupported()
public abstract boolean startFlush(List<Address> flushParticipants, boolean automatic_resume)
public abstract boolean startFlush(boolean automatic_resume)
public abstract boolean startFlush(long timeout, boolean automatic_resume)
public abstract void stopFlush()
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) throws ChannelNotConnectedException, ChannelClosedException
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).ChannelNotConnectedException
- The channel must be connected to receive messages.ChannelClosedException
- The channel is closed and therefore cannot be used
any longer. A new channel has to be created first.public abstract boolean getState(Address target, String state_id, long timeout) throws ChannelNotConnectedException, ChannelClosedException
target
- state_id
- timeout
- ChannelNotConnectedException
ChannelClosedException
public abstract boolean getAllStates(Vector targets, long timeout) throws ChannelNotConnectedException, ChannelClosedException
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).ChannelNotConnectedException
- The channel must be connected to
receive messages.ChannelClosedException
- The channel is closed and therefore cannot be used
any longer. A new channel has to be created first.public abstract void returnState(byte[] state)
getState()
object when calling receive()
.state
- The state of the application as a byte buffer
(to send over the network).public abstract void returnState(byte[] state, String state_id)
public static String option2String(int option)
protected void notifyChannelConnected(Channel c)
protected void notifyChannelDisconnected(Channel c)
protected void notifyChannelClosed(Channel c)
Copyright © 2013 JBoss, a division of Red Hat. All Rights Reserved.