JChannel (JBoss Application Server: Build 7.1.2.Final API)

java.lang.Object
- org.jgroups.Channel
- - org.jgroups.JChannel

```
public class JChannel
extends Channel
```
JChannel is a default implementation of a Channel abstraction.
JChannel is instantiated using an appropriate form of a protocol stack description. Protocol stack can be described using a file, URL or a stream containing XML stack description.

Since:

2.0

Author:

Bela Ban

Field Summary

Fields
Modifier and Type	Field and Description
`protected AddressGenerator`	`address_generator`
`protected boolean`	`closed` channel closed flag
`protected ConcurrentMap<String,Object>`	`config`
`protected boolean`	`connected` channel connected flag
`static String`	`DEFAULT_PROTOCOL_STACK` The default protocol stack used by the default constructor
`protected Address`	`local_addr`
`protected Log`	`log`
`protected String`	`name`
`protected long`	`received_bytes`
`protected long`	`received_msgs`
`protected long`	`sent_bytes`
`protected long`	`sent_msgs`
`protected boolean`	`stats` Collect statistics

Fields inherited from class org.jgroups.Channel
channel_listeners, discard_own_messages, receiver, socket_factory, up_handler

Constructor Summary

Constructors
Constructor and Description
`JChannel()` Constructs a `JChannel` instance with the protocol stack specified by the `DEFAULT_PROTOCOL_STACK` member.
`JChannel(boolean create_protocol_stack)` Creates a JChannel without a protocol stack; used for programmatic creation of channel and protocol stack
`JChannel(Element properties)` Constructs a JChannel instance with the protocol stack configuration contained by the specified XML element.
`JChannel(File properties)` Constructs a JChannel instance with the protocol stack configuration contained by the specified file.
`JChannel(InputStream input)` Creates a channel with a configuration based on an input stream.
`JChannel(JChannel ch)` Creates a channel with the same configuration as the channel passed to this constructor.
`JChannel(ProtocolStackConfigurator configurator)` Constructs a JChannel with the protocol stack configuration contained by the protocol stack configurator parameter.
`JChannel(String props)` Constructs a JChannel instance with the protocol stack configuration based upon the specified properties parameter.
`JChannel(URL properties)` Constructs a JChannel instance with the protocol stack configuration indicated by the specified URL.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`_close(boolean disconnect)` Disconnects and closes the channel.
`protected void`	`checkClosed()` health check throws a ChannelClosed exception if the channel is closed
`protected void`	`checkClosedOrNotConnected()`
`void`	`close()` Destroys the channel and its associated resources (e.g., the protocol stack).
`void`	`connect(String cluster_name)` Connects the channel to a group.
`void`	`connect(String cluster_name, Address target, long timeout)` Connects this channel to a group and gets a state from a specified state provider.
`void`	`connect(String cluster_name, Address target, long timeout, boolean useFlushIfPresent)` Connects this channel to a group and gets a state from a specified state provider. This method invokes `connect() and then getState.` `If the FLUSH protocol is in the channel's stack definition, only one flush round is executed for both connecting and fetching the state rather than two flushes if we invoke connect and getState in succession.`
`protected void`	`connect(String cluster_name, boolean useFlushIfPresent)` Connects the channel to a group.
`void`	`disconnect()` Disconnects the channel if it is connected.
`Object`	`down(Event evt)` Sends a message through the protocol stack if the stack is available
`protected Map<String,Long>`	`dumpChannelStats()`
`Map<String,Object>`	`dumpStats()` Returns a map of statistics of the various protocols and of the channel itself.
`Map<String,Object>`	`dumpStats(String protocol_name)`
`Map<String,Object>`	`dumpStats(String protocol_name, List<String> attrs)`
`String`	`dumpTimerQueue()`
`void`	`enableStats(boolean stats)`
`boolean`	`flushSupported()`
`Address`	`getAddress()` Returns the channel's own address.
`String`	`getAddressAsString()`
`String`	`getAddressAsUUID()`
`AddressGenerator`	`getAddressGenerator()` Returns the current `AddressGenerator`, or null if none is set
`String`	`getClusterName()` Returns the cluster name of the group of which the channel is a member.
`protected Log`	`getLog()`
`String`	`getName()` Returns the logical name of this channel if set.
`String`	`getName(Address member)` Returns the logical name of a given member.
`int`	`getNumberOfTasksInTimer()`
`String`	`getProperties()` Returns the protocol stack configuration in string format.
`ProtocolStack`	`getProtocolStack()` Returns the protocol stack
`long`	`getReceivedBytes()`
`long`	`getReceivedMessages()`
`long`	`getSentBytes()`
`long`	`getSentMessages()`
`void`	`getState(Address target, long timeout)` Retrieves the full state from the target member.
`void`	`getState(Address target, long timeout, boolean useFlushIfPresent)` Retrieves state from the target member.
`protected void`	`getState(Address target, long timeout, Callable<Boolean> flushInvoker)`
`int`	`getTimerThreads()`
`static String`	`getVersion()`
`View`	`getView()` Gets the current view.
`String`	`getViewAsString()`
`protected void`	`init(JChannel ch)`
`protected void`	`init(ProtocolStackConfigurator configurator)`
`protected Object`	`invokeCallback(int type, Object arg)`
`boolean`	`isConnected()` Determines whether the channel is connected to a group.
`boolean`	`isOpen()` Determines whether the channel is open; ie.
`String`	`printProtocolSpec(boolean include_properties)` Returns a pretty-printed form of all the protocols.
`void`	`resetStats()`
`void`	`send(Address dst, byte[] buf)` Sends a message.
`void`	`send(Address dst, byte[] buf, int offset, int length)` Sends a message to a destination.
`void`	`send(Address dst, Object obj)` Helper method to create a Message with given parameters and invoke `Channel.send(Message)`.
`void`	`send(Message msg)` Sends a message.
`protected void`	`setAddress()` Generates new UUID and sets local address.
`void`	`setAddressGenerator(AddressGenerator address_generator)` Sets the new `AddressGenerator`.
`void`	`setName(String name)` Sets the logical name for the channel.
`void`	`setProtocolStack(ProtocolStack stack)`
`void`	`startFlush(boolean automatic_resume)` Will perform a flush of the system, ie.
`void`	`startFlush(List<Address> flushParticipants, boolean automatic_resume)` Performs a partial flush in a cluster for flush participants.
`boolean`	`statsEnabled()`
`void`	`stopFlush()`
`void`	`stopFlush(List<Address> flushParticipants)`
`protected void`	`stopStack(boolean stop, boolean destroy)`
`String`	`toString(boolean details)`
`Object`	`up(Event evt)` Callback method Called by the ProtocolStack when a message is received.

Methods inherited from class org.jgroups.Channel
addChannelListener, clearChannelListeners, getDiscardOwnMessages, getReceiver, getSocketFactory, getUpHandler, notifyChannelClosed, notifyChannelConnected, notifyChannelDisconnected, removeChannelListener, setDiscardOwnMessages, setReceiver, setSocketFactory, setUpHandler

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_PROTOCOL_STACK
```
public static final String DEFAULT_PROTOCOL_STACK
```
    The default protocol stack used by the default constructor
    
    See Also:
    Constant Field Values
  - local_addr
```
protected Address local_addr
```
  - address_generator
```
protected AddressGenerator address_generator
```
  - name
```
protected String name
```
  - connected
```
protected volatile boolean connected
```
    channel connected flag
  - closed
```
protected volatile boolean closed
```
    channel closed flag
  - config
```
protected final ConcurrentMap<String,Object> config
```
  - log
```
protected final Log log
```
  - stats
```
protected boolean stats
```
    Collect statistics
  - sent_msgs
```
protected long sent_msgs
```
  - received_msgs
```
protected long received_msgs
```
  - sent_bytes
```
protected long sent_bytes
```
  - received_bytes
```
protected long received_bytes
```
- Constructor Detail
  - JChannel
```
public JChannel(boolean create_protocol_stack)
```
    Creates a JChannel without a protocol stack; used for programmatic creation of channel and protocol stack
    
    Parameters:
    create_protocol_stack - If true, the default configuration will be used. If false, no protocol stack will be created
    create_protocol_stack - Creates the default stack if true, or no stack if false
  - JChannel
```
public JChannel()
         throws Exception
```
    Constructs a JChannel instance with the protocol stack specified by the DEFAULT_PROTOCOL_STACK member.
    
    Throws:
    
    Exception - If problems occur during the initialization of the protocol stack.
  - JChannel
```
public JChannel(File properties)
         throws Exception
```
    Constructs a JChannel instance with the protocol stack configuration contained by the specified file.
    
    Parameters:
    properties - A file containing a JGroups XML protocol stack configuration.
    
    Throws:
    
    Exception - If problems occur during the configuration or initialization of the protocol stack.
  - JChannel
```
public JChannel(Element properties)
         throws Exception
```
    Constructs a JChannel instance with the protocol stack configuration contained by the specified XML element.
    
    Parameters:
    properties - An XML element containing a JGroups XML protocol stack configuration.
    
    Throws:
    
    Exception - If problems occur during the configuration or initialization of the protocol stack.
  - JChannel
```
public JChannel(URL properties)
         throws Exception
```
    Constructs a JChannel instance with the protocol stack configuration indicated by the specified URL.
    
    Parameters:
    properties - A URL pointing to a JGroups XML protocol stack configuration.
    
    Throws:
    
    Exception - If problems occur during the configuration or initialization of the protocol stack.
  - JChannel
```
public JChannel(String props)
         throws Exception
```
    Constructs a JChannel instance with the protocol stack configuration based upon the specified properties parameter.
    
    Parameters:
    props - A file containing a JGroups XML configuration, a URL pointing to an XML configuration, or an old style plain configuration string.
    
    Throws:
    
    Exception - If problems occur during the configuration or initialization of the protocol stack.
  - JChannel
```
public JChannel(InputStream input)
         throws Exception
```
    Creates a channel with a configuration based on an input stream.
    
    Parameters:
    input - An input stream, pointing to a streamed configuration
    
    Throws:
    
    Exception
  - JChannel
```
public JChannel(ProtocolStackConfigurator configurator)
         throws Exception
```
    Constructs a JChannel with the protocol stack configuration contained by the protocol stack configurator parameter.
    All of the public constructors of this class eventually delegate to this method.
    
    Parameters:
    configurator - A protocol stack configurator containing a JGroups protocol stack configuration.
    
    Throws:
    
    Exception - If problems occur during the initialization of the protocol stack.
  - JChannel
```
public JChannel(JChannel ch)
         throws Exception
```
    Creates a channel with the same configuration as the channel passed to this constructor. This is used by testing code, and should not be used by clients !
    
    Parameters:
    ch -
    
    Throws:
    
    Exception
- Method Detail
  - getProtocolStack
```
public ProtocolStack getProtocolStack()
```
    Returns the protocol stack
    
    Specified by:
    
    getProtocolStack in class Channel
  - setProtocolStack
```
public void setProtocolStack(ProtocolStack stack)
```
  - getLog
```
protected Log getLog()
```
    Specified by:
    
    getLog in class Channel
  - getProperties
```
public String getProperties()
```
    Returns the protocol stack configuration in string format. An example of this property is
    "UDP:PING:FD:STABLE:NAKACK:UNICAST:FRAG:FLUSH:GMS:VIEW_ENFORCER:STATE_TRANSFER:QUEUE"
    
    Overrides:
    
    getProperties in class Channel
  - statsEnabled
```
public boolean statsEnabled()
```
  - enableStats
```
public void enableStats(boolean stats)
```
  - resetStats
```
public void resetStats()
```
  - getSentMessages
```
public long getSentMessages()
```
  - getSentBytes
```
public long getSentBytes()
```
  - getReceivedMessages
```
public long getReceivedMessages()
```
  - getReceivedBytes
```
public long getReceivedBytes()
```
  - getNumberOfTasksInTimer
```
public int getNumberOfTasksInTimer()
```
  - getTimerThreads
```
public int getTimerThreads()
```
  - dumpTimerQueue
```
public String dumpTimerQueue()
```
  - printProtocolSpec
```
public String printProtocolSpec(boolean include_properties)
```
    Returns a pretty-printed form of all the protocols. If include_properties is set, the properties for each protocol will also be printed.
  - connect
```
public void connect(String cluster_name)
             throws Exception
```
    Description copied from class: Channel
    
    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.
    
    Specified by:
    
    connect in class Channel
    
    Parameters:
    cluster_name - The name of the channel to connect to.
    
    Throws:
    
    Exception - The protocol stack cannot be started
    
    IllegalStateException - The channel is closed
  - connect
```
protected void connect(String cluster_name,
           boolean useFlushIfPresent)
                throws Exception
```
    Connects the channel to a group.
    
    Throws:
    
    Exception
    See Also:
    connect(String)
  - connect
```
public void connect(String cluster_name,
           Address target,
           long timeout)
             throws Exception
```
    Description copied from class: Channel
    
    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.
    Specified by: connect in class Channel 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: Exception - Connecting to the cluster or state transfer was not successful IllegalStateException - The channel is closed and therefore cannot be used
  connect public void connect(String cluster_name, Address target, long timeout, boolean useFlushIfPresent) throws Exception Connects this channel to a group and gets a state from a specified state provider. This method invokes connect() and then getState. If the FLUSH protocol is in the channel's stack definition, only one flush round is executed for both connecting and fetching the state rather than two flushes if we invoke connect and getState in succession. If the channel is already connected, an error message will be printed to the error log. If the channel is closed a ChannelClosed exception will be thrown. Parameters: cluster_name - The cluster name to connect to. Cannot be null. target - The state provider. If null, the state will be fetched from the coordinator, unless this channel is the coordinator. timeout - The timeout for the state transfer. Throws: Exception - The protocol stack cannot be started, or the JOIN failed IllegalStateException - The channel is closed or disconnected StateTransferException - State transfer was not successful disconnect public void disconnect() Description copied from class: Channel 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. Specified by: disconnect in class Channel See Also: Channel.connect(String) close public void close() Description copied from class: Channel 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 class Channel isOpen public boolean isOpen() Description copied from class: Channel Determines whether the channel is open; ie. the protocol stack has been created (may not be connected though). Specified by: isOpen in class Channel Returns: true is channel is open, false otherwise isConnected public boolean isConnected() Description copied from class: Channel Determines whether the channel is connected to a group. Specified by: isConnected in class Channel Returns: true if channel is connected to cluster (group) and can send/receive messages, false otherwise dumpStats public Map<String,Object> dumpStats() Description copied from class: Channel Returns a map of statistics of the various protocols and of the channel itself. Specified by: dumpStats in class Channel 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. dumpStats public Map<String,Object> dumpStats(String protocol_name, List<String> attrs) dumpStats public Map<String,Object> dumpStats(String protocol_name) dumpChannelStats protected Map<String,Long> dumpChannelStats() send public void send(Message msg) throws Exception Description copied from class: Channel 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 Specified by: send in class Channel Parameters: msg - The message to be sent. Destination and buffer should be set. A null destination means to send to all group members. Throws: IllegalStateException - thrown if the channel is disconnected or closed Exception send public void send(Address dst, Object obj) throws Exception Description copied from class: Channel Helper method to create a Message with given parameters and invoke Channel.send(Message). Specified by: send in class Channel 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: Exception - exception thrown if message sending was not successful send public void send(Address dst, byte[] buf) throws Exception Description copied from class: Channel Sends a message. See Channel.send(Address,byte[],int,int) for details Specified by: send in class Channel Parameters: dst - destination address for message. If null, message will be sent to all current group members buf - buffer message payload Throws: Exception - exception thrown if message sending was not successful send public void send(Address dst, byte[] buf, int offset, int length) throws Exception Description copied from class: Channel Sends a message to a destination. Specified by: send in class Channel 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: Exception - If send() failed getView public View getView() Description copied from class: Channel 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. Specified by: getView in class Channel Returns: The current view. getViewAsString public String getViewAsString() getVersion public static String getVersion() getAddress public Address getAddress() Description copied from class: Channel 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. Specified by: getAddress in class Channel Returns: The channel's address (opaque) getAddressAsString public String getAddressAsString() getAddressAsUUID public String getAddressAsUUID() getName public String getName() Description copied from class: Channel Returns the logical name of this channel if set. Specified by: getName in class Channel Returns: The logical name or null (if not set) getName public String getName(Address member) Description copied from class: Channel 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. Specified by: getName in class Channel Returns: The logical name for member setName public void setName(String name) Description copied from class: Channel 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(). Specified by: setName in class Channel getClusterName public String getClusterName() Description copied from class: Channel 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. Specified by: getClusterName in class Channel Returns: The cluster name getAddressGenerator public AddressGenerator getAddressGenerator() Returns the current AddressGenerator, or null if none is set Returns: Since: 2.12 setAddressGenerator public void setAddressGenerator(AddressGenerator address_generator) Sets the new AddressGenerator. New addresses will be generated using the new generator. This should not be done while a channel is connected, but before connecting. Parameters: address_generator - Since: 2.12 getState public void getState(Address target, long timeout) throws Exception Description copied from class: Channel 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. Specified by: getState in class Channel 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: IllegalStateException - The channel was closed or disconnected, or the flush (if present) failed StateTransferException - raised if there was a problem during the state transfer Exception See Also: MessageListener.getState(java.io.OutputStream), MessageListener.setState(java.io.InputStream) getState public void getState(Address target, long timeout, boolean useFlushIfPresent) throws Exception Retrieves state from the target member. See getState(Address,long) for details. Throws: Exception getState protected void getState(Address target, long timeout, Callable<Boolean> flushInvoker) throws Exception Throws: Exception up public Object up(Event evt) Callback method Called by the ProtocolStack when a message is received. Parameters: evt - the event carrying the message from the protocol stack down public Object down(Event evt) Sends a message through the protocol stack if the stack is available Overrides: down in class Channel Parameters: evt - the message to send down, encapsulated in an event Returns: a response from a particular protocol layer targeted by Event parameter toString public String toString(boolean details) invokeCallback protected Object invokeCallback(int type, Object arg) init protected final void init(ProtocolStackConfigurator configurator) throws Exception Throws: Exception init protected final void init(JChannel ch) throws Exception Throws: Exception setAddress protected void setAddress() Generates new UUID and sets local address. Sends down a REMOVE_ADDRESS (if existing address was present) and a SET_LOCAL_ADDRESS checkClosed protected void checkClosed() health check throws a ChannelClosed exception if the channel is closed checkClosedOrNotConnected protected void checkClosedOrNotConnected() _close protected void _close(boolean disconnect) Disconnects and closes the channel. This method does the following things Calls this.disconnect if the disconnect parameter is true Calls ProtocolStack.stop on the protocol stack Calls ProtocolStack.destroy on the protocol stack Sets the channel closed and channel connected flags to true and false Notifies any channel listener of the channel close operation stopStack protected void stopStack(boolean stop, boolean destroy) flushSupported public boolean flushSupported() Specified by: flushSupported in class Channel startFlush public void startFlush(boolean automatic_resume) throws Exception Description copied from class: Channel 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 Channel.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. Specified by: startFlush in class Channel Parameters: automatic_resume - if true call Channel.stopFlush() after the flush Throws: Exception startFlush public void startFlush(List<Address> flushParticipants, boolean automatic_resume) throws Exception Description copied from class: Channel 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. Specified by: startFlush in class Channel automatic_resume - if true call Channel.stopFlush() after the flush Throws: Exception See Also: Channel.startFlush(boolean) stopFlush public void stopFlush() Specified by: stopFlush in class Channel stopFlush public void stopFlush(List<Address> flushParticipants) Specified by: stopFlush in class Channel

Class JChannel

Field Summary

Fields inherited from class org.jgroups.Channel

Constructor Summary

Method Summary

Methods inherited from class org.jgroups.Channel

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_PROTOCOL_STACK

local_addr

address_generator

name

connected

closed

config

log

stats

sent_msgs

received_msgs

sent_bytes

received_bytes

Constructor Detail

JChannel

JChannel

JChannel

JChannel

JChannel

JChannel

JChannel

JChannel

JChannel

Method Detail

getProtocolStack

setProtocolStack

getLog

getProperties

statsEnabled

enableStats

resetStats

getSentMessages

getSentBytes

getReceivedMessages

getReceivedBytes

getNumberOfTasksInTimer

getTimerThreads

dumpTimerQueue

printProtocolSpec

connect

connect

connect

connect

disconnect

close

isOpen

isConnected

dumpStats

dumpStats

dumpStats

dumpChannelStats

send

send

send

send

getView

getViewAsString

getVersion

getAddress

getAddressAsString

getAddressAsUUID

getName

getName

setName

getClusterName

getAddressGenerator

setAddressGenerator

getState

getState

getState

up

down