Channel

java.lang.Object
- org.jgroups.Channel

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

Direct Known Subclasses:

JChannel
```
public abstract class Channel
extends java.lang.Object
implements java.io.Closeable
```
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

Nested Classes
Modifier and Type Class and Description

static class Channel.State

Nested Classes
Modifier and Type	Class and Description
`static class`	`Channel.State`

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.util.Set<ChannelListener>`	`channel_listeners`
`protected boolean`	`discard_own_messages`
`protected Log`	`log`
`protected Receiver`	`receiver`
`protected SocketFactory`	`socket_factory`
`protected Channel.State`	`state` The current state of the channel
`protected UpHandler`	`up_handler`

Constructor Summary

Constructors
Constructor and Description

Channel()

Constructors
Constructor and Description
`Channel()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`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
`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.
`abstract Channel`	`name(java.lang.String name)` Names a channel, same as `setName(String)`
`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)` Performs the flush of the cluster, ie.
`abstract void`	`startFlush(java.util.List<Address> flushParticipants, boolean automatic_resume)` Performs the flush of the cluster but only for the specified flush participants.
`abstract void`	`stopFlush()` Stops the current flush of the cluster.
`abstract void`	`stopFlush(java.util.List<Address> flushParticipants)` Stops the current flush of the cluster for the specified flush participants.

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
```
  - log
```
protected final Log log
```
  - discard_own_messages
```
protected boolean discard_own_messages
```
- Constructor Detail
  - Channel
```
public Channel()
```
- Method Detail
  - getState
```
public java.lang.String getState()
```
  - 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. Specified by: close in interface java.io.Closeable Specified by: close in interface java.lang.AutoCloseable 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 a destination address (Address). A null address sends the message to all group members. a source address. Can be left empty as it will be assigned automatically a byte buffer. The message contents. 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: evt - sends an Event to a specific protocol layer and receives 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 - name public abstract Channel name(java.lang.String name) Names a channel, same as setName(String) 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: up_handler - 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 the flush of the cluster but only for the specified flush participants. All pending messages are flushed out but only for the flush participants. The remaining members in the cluster are not included in the flush. The list of flush participants should be a proper subset of the current view. If this flush is not automatically resumed it is an obligation of the application to invoke the matching stopFlush(List) method with the same list of members used in startFlush(List, boolean). Parameters: automatic_resume - if true call stopFlush() after the flush Throws: java.lang.Exception See Also: startFlush(boolean), Util.startFlush(Channel, List, int, long, long) startFlush public abstract void startFlush(boolean automatic_resume) throws java.lang.Exception Performs the flush of the cluster, ie. all pending application messages are flushed out of the cluster and all members ack their reception. After this call returns, no member will be allowed to send any messages until stopFlush() is called. In the case of flush collisions (another member attempts flush at roughly the same time) start flush will fail by throwing an Exception. Applications can re-attempt flushing after certain back-off period. JGroups provides a helper random sleep time backoff algorithm for flush using Util class. Parameters: automatic_resume - if true call stopFlush() after the flush Throws: java.lang.Exception See Also: Util.startFlush(Channel, List, int, long, long) stopFlush public abstract void stopFlush() Stops the current flush of the cluster. Cluster members are unblocked and allowed to send new and pending messages. See Also: startFlush(boolean), startFlush(List, boolean) stopFlush public abstract void stopFlush(java.util.List<Address> flushParticipants) Stops the current flush of the cluster for the specified flush participants. Flush participants are unblocked and allowed to send new and pending messages. It is an obligation of the application to invoke the matching startFlush(List, boolean) method with the same list of members prior to invocation of this method. Parameters: flushParticipants - the flush participants 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)

Class Channel

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

state

up_handler

channel_listeners

receiver

socket_factory

log

discard_own_messages

Constructor Detail

Channel

Method Detail

getState

getProtocolStack

getSocketFactory

setSocketFactory

connect

connect

disconnect

close

isOpen

isConnected

isConnecting

isClosed

dumpStats

send

send

send

send

down

getView

getAddress

getName

getName

setName

name

getClusterName

getProperties

setUpHandler

getUpHandler

addChannelListener

removeChannelListener

clearChannelListeners

setReceiver

getReceiver

setDiscardOwnMessages

getDiscardOwnMessages

flushSupported

startFlush

startFlush

stopFlush

stopFlush

getState

notifyChannelConnected

notifyChannelDisconnected

notifyChannelClosed