org.jgroups
Class Channel

java.lang.Object
  org.jgroups.Channel

Direct Known Subclasses:

JChannel

public abstract class Channel
extends java.lang.Object

A channel represents a group communication endpoint (like BSD datagram sockets). A client joins a group by connecting the channel to a group 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 name).

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 setting a Receiver in setReceiver(Receiver) and implementing the MessageListener.receive(Message) callback.

A channel instance is created using the public constructor.

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.

Since:

2.0

Author:

Bela Ban

See Also:

DatagramPacket, MulticastSocket, JChannel

Nested Class Summary

static class

Channel.State

Field Summary

protected java.util.Set<ChannelListener>	channel_listeners
protected boolean	discard_own_messages
protected Receiver	receiver
protected SocketFactory	socket_factory
protected Channel.State	state The current state of the channel
protected UpHandler	up_handler

Constructor Summary

Channel()

Method Summary

void	addChannelListener(ChannelListener listener) Adds a ChannelListener instance that will be notified when a channel event such as connect, disconnect or close occurs.
void	clearChannelListeners() Clears all installed ChannelListener instances
abstract void	close() Destroys the channel and its associated resources (e.g., the protocol stack).
abstract void	connect(java.lang.String cluster_name) Connects the channel to a group.
abstract void	connect(java.lang.String cluster_name, Address target, long timeout) Connects this channel to a group and gets a state from a specified state provider.
abstract void	disconnect() Disconnects the channel if it is connected.
java.lang.Object	down(Event evt) Enables access to event mechanism of a channel and is normally not used by clients directly.
abstract java.util.Map<java.lang.String,java.lang.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 java.lang.String	getClusterName() Returns the cluster name of the group of which the channel is a member.
boolean	getDiscardOwnMessages() Returns true if this channel will discard its own messages, false otherwise
protected abstract Log	getLog()
abstract java.lang.String	getName() Returns the logical name of this channel if set.
abstract java.lang.String	getName(Address member) Returns the logical name of a given member.
java.lang.String	getProperties()
abstract ProtocolStack	getProtocolStack()
Receiver	getReceiver() Returns a receiver for this channel if it has been installed using setReceiver(Receiver) , null otherwise
SocketFactory	getSocketFactory()
java.lang.String	getState()
abstract void	getState(Address target, long timeout) Retrieves the full state from the target member.
UpHandler	getUpHandler() Returns UpHandler installed for this channel
abstract View	getView() Gets the current view.
boolean	isClosed() Determines whether the channel is in the closed state.
boolean	isConnected() Determines whether the channel is connected to a group.
boolean	isConnecting() Determines whether the channel is in the connecting state; this means connect(String) has been called, but hasn't returned yet
boolean	isOpen() Determines whether the channel is open; ie.
protected void	notifyChannelClosed(Channel c)
protected void	notifyChannelConnected(Channel c)
protected void	notifyChannelDisconnected(Channel c)
void	removeChannelListener(ChannelListener listener) Removes a ChannelListener previously installed
abstract void	send(Address dst, byte[] buf) Sends a message.
abstract void	send(Address dst, byte[] buf, int offset, int length) Sends a message to a destination.
abstract void	send(Address dst, java.lang.Object obj) Helper method to create a Message with given parameters and invoke send(Message).
abstract void	send(Message msg) Sends a message.
void	setDiscardOwnMessages(boolean flag) When set to true, all messages sent by a member A will be discarded by A.
abstract void	setName(java.lang.String name) Sets the logical name for the channel.
void	setReceiver(Receiver r) Sets the receiver for this channel.
void	setSocketFactory(SocketFactory factory)
void	setUpHandler(UpHandler up_handler) Sets this channel event handler to be a recipient off all events .
abstract void	startFlush(boolean automatic_resume) Will perform a flush of the system, ie.
abstract void	startFlush(java.util.List<Address> flushParticipants, boolean automatic_resume) Performs a partial flush in a cluster for flush participants.
abstract void	stopFlush()
abstract void	stopFlush(java.util.List<Address> flushParticipants)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

state

protected volatile Channel.State state

The current state of the channel

up_handler

protected UpHandler up_handler

channel_listeners

protected java.util.Set<ChannelListener> channel_listeners

receiver

protected Receiver receiver

socket_factory

protected SocketFactory socket_factory

discard_own_messages

protected boolean discard_own_messages

Constructor Detail

Channel

public Channel()

Method Detail

getState

public java.lang.String getState()

getLog

protected abstract Log getLog()

getProtocolStack

public abstract ProtocolStack getProtocolStack()

getSocketFactory

public SocketFactory getSocketFactory()

setSocketFactory

public void setSocketFactory(SocketFactory factory)

connect

public abstract void connect(java.lang.String cluster_name)
                      throws java.lang.Exception

Connects the channel to a group. The client is now able to receive group messages, views 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 cluster name.

Parameters:

cluster_name - The name of the channel to connect to.

Throws:

java.lang.Exception - The protocol stack cannot be started

java.lang.IllegalStateException - The channel is closed

connect

public abstract void connect(java.lang.String cluster_name,
                             Address target,
                             long timeout)
                      throws java.lang.Exception

Connects this channel to a group and gets a state from a specified state provider.

This method essentially invokes connect and getState methods successively. If FLUSH protocol is in channel's stack definition only one flush is executed for both connecting and fetching state rather than two flushes if we invoke connect and getState in succession. If the channel is closed an exception will be thrown.

Parameters:

cluster_name - the cluster name to connect to. Cannot be null.

target - the state provider. If null state will be fetched from coordinator, unless this channel is coordinator.

timeout - the timeout for state transfer.

Throws:

java.lang.Exception - Connecting to the cluster or state transfer was not successful

java.lang.IllegalStateException - The channel is closed and therefore cannot be used

disconnect

public abstract void disconnect()

Disconnects the channel if it is connected. If the channel is closed or disconnected, this operation is ignored
The channel can then be connected to the same or a different cluster again.

See Also:

connect(String)

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.

isOpen

public boolean isOpen()

Determines whether the channel is open; ie. the protocol stack has been created (may not be connected though).

Returns:

true is channel is open, false otherwise

isConnected

public boolean isConnected()

Determines whether the channel is connected to a group.

Returns:

true if channel is connected to cluster (group) and can send/receive messages, false otherwise

isConnecting

public boolean isConnecting()

Determines whether the channel is in the connecting state; this means connect(String) has been called, but hasn't returned yet

Returns:

true if the channel is in the connecting state, false otherwise

isClosed

public boolean isClosed()

Determines whether the channel is in the closed state.

Returns:

dumpStats

public abstract java.util.Map<java.lang.String,java.lang.Object> dumpStats()

Returns a map of statistics of the various protocols and of the channel itself.

Returns:

Map. A map where the keys are the protocols ("channel" pseudo key is used for the channel itself") and the values are property maps.

send

public abstract void send(Message msg)
                   throws java.lang.Exception

Sends a message. 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 as it will be assigned automatically
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, flags 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:

java.lang.IllegalStateException - thrown if the channel is disconnected or closed

java.lang.Exception

send

public abstract void send(Address dst,
                          java.lang.Object obj)
                   throws java.lang.Exception

Helper method to create a Message with given parameters and invoke send(Message).

Parameters:

dst - Destination address for message. If null, message will be sent to all current group members

obj - A serializable object. Will be marshalled into the byte buffer of the Message. If it is not serializable, an exception will be thrown

Throws:

java.lang.Exception - exception thrown if message sending was not successful

send

public abstract void send(Address dst,
                          byte[] buf)
                   throws java.lang.Exception

Sends a message. See send(Address,byte[],int,int) for details

Parameters:

dst - destination address for message. If null, message will be sent to all current group members

buf - buffer message payload

Throws:

java.lang.Exception - exception thrown if message sending was not successful

send

public abstract void send(Address dst,
                          byte[] buf,
                          int offset,
                          int length)
                   throws java.lang.Exception

Sends a message to a destination.

Parameters:

dst - The destination address. If null, the message will be sent to all cluster nodes (= group members)

buf - The buffer to be sent

offset - The offset into the buffer

length - The length of the data to be sent. Has to be <= buf.length - offset. This will send length bytes starting at offset

Throws:

java.lang.Exception - If send() failed

down

public java.lang.Object down(Event evt)

Enables access to event mechanism of a channel and is normally not used by clients directly.

Parameters:

sends - an Event to a specific protocol layer and receive a response.

Returns:

a response from a particular protocol layer targeted by Event parameter

getView

public abstract View getView()

Gets the current view. 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 this method on a closed channel returns a null view.

Returns:

The current view.

getAddress

public abstract Address getAddress()

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. Addresses can be used as destination in the send() operation.

Returns:

The channel's address (opaque)

getName

public abstract java.lang.String getName()

Returns the logical name of this channel if set.

Returns:

The logical name or null (if not set)

getName

public abstract java.lang.String getName(Address member)

Returns the logical name of a given member. The lookup is from the local cache of logical address / logical name mappings and no remote communication is performed.

Parameters:

member -

Returns:

The logical name for member

setName

public abstract void setName(java.lang.String name)

Sets the logical name for the channel. The name will stay associated with this channel for the channel's lifetime (until close() is called). This method should be called before calling connect().

Parameters:

name -

getClusterName

public abstract java.lang.String getClusterName()

Returns the cluster name 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 cluster name

getProperties

public java.lang.String getProperties()

setUpHandler

public void setUpHandler(UpHandler up_handler)

Sets this channel event handler to be a recipient off all events . 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.

Parameters:

the - handler to handle channel events

getUpHandler

public UpHandler getUpHandler()

Returns UpHandler installed for this channel

Returns:

the installed UpHandler implementation

addChannelListener

public void addChannelListener(ChannelListener listener)

Adds a ChannelListener instance that will be notified when a channel event such as connect, disconnect or close occurs.

Parameters:

listener - to be notified

removeChannelListener

public void removeChannelListener(ChannelListener listener)

Removes a ChannelListener previously installed

Parameters:

listener - to be removed

clearChannelListeners

public void clearChannelListeners()

Clears all installed ChannelListener instances

setReceiver

public void setReceiver(Receiver r)

Sets the receiver for this channel. Receiver will in turn handle all messages, view changes, implement state transfer logic and so on.

Parameters:

r - the receiver instance for this channel

See Also:

Receiver

getReceiver

public Receiver getReceiver()

Returns a receiver for this channel if it has been installed using setReceiver(Receiver) , null otherwise

Returns:

a receiver installed on this channel

setDiscardOwnMessages

public void setDiscardOwnMessages(boolean flag)

When set to true, all messages sent by a member A will be discarded by A.

Parameters:

flag -

getDiscardOwnMessages

public boolean getDiscardOwnMessages()

Returns true if this channel will discard its own messages, false otherwise

Returns:

flushSupported

public abstract boolean flushSupported()

startFlush

public abstract void startFlush(java.util.List<Address> flushParticipants,
                                boolean automatic_resume)
                         throws java.lang.Exception

Performs a partial flush in a cluster for flush participants.

All pending messages are flushed out only for the flush participants. The remaining members in a cluster are not included in the flush. The flush participants should be a proper subset of a current view.

Parameters:

automatic_resume - if true call stopFlush() after the flush

Throws:

java.lang.Exception

See Also:

startFlush(boolean)

startFlush

public abstract void startFlush(boolean automatic_resume)
                         throws java.lang.Exception

Will perform a flush of the system, ie. all pending messages are flushed out of the system and all members ack their reception. After this call returns, no member will be sending any messages until stopFlush() is called.

In case of flush collisions, a random sleep time backoff algorithm is employed and the flush is reattempted for numberOfAttempts. Therefore this method is guaranteed to return after timeout x numberOfAttempts milliseconds.

Parameters:

automatic_resume - if true call stopFlush() after the flush

Throws:

java.lang.Exception

stopFlush

public abstract void stopFlush()

stopFlush

public abstract void stopFlush(java.util.List<Address> flushParticipants)

getState

public abstract void getState(Address target,
                              long timeout)
                       throws java.lang.Exception

Retrieves the full state from the target member.

State transfer is initiated by invoking getState on this channel. The state provider in turn invokes MessageListener.getState(java.io.OutputStream) callback and sends a state to this node, the state receiver. After the state arrives to the state receiver MessageListener.setState(java.io.InputStream) callback is invoked to install the state.

Parameters:

target - The state provider. If null the coordinator is used by default

timeout - The number of milliseconds to wait for the operation to complete successfully. 0 waits until the state has been received

Throws:

java.lang.IllegalStateException - The channel was closed or disconnected, or the flush (if present) failed

StateTransferException - raised if there was a problem during the state transfer

java.lang.Exception

See Also:

MessageListener.getState(java.io.OutputStream), MessageListener.setState(java.io.InputStream)

notifyChannelConnected

protected void notifyChannelConnected(Channel c)

notifyChannelDisconnected

protected void notifyChannelDisconnected(Channel c)

notifyChannelClosed

protected void notifyChannelClosed(Channel c)