org.jgroups

## Class JChannel

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

- All Implemented Interfaces:
    Transport
  Direct Known Subclasses:
    MuxChannel

      public class JChannel
      extends Channel

  JChannel is a pure Java implementation of Channel. When a JChannel object is instantiated it automatically sets up the protocol stack.

  Properties

  Properties are used to configure a channel, and are accepted in several forms; the String form is described here. A property string consists of a number of properties separated by colons. For example:

      "<prop1>(arg1=val1):<prop2>(arg1=val1;arg2=val2):<prop3>:<propn>"

  Each property relates directly to a protocol layer, which is implemented as a Java class. When a protocol stack is to be created based on the above property string, the first property becomes the bottom-most layer, the second one will be placed on the first, etc.: the stack is created from the bottom to the top, as the string is parsed from left to right. Each property has to be the name of a Java class that resides in the `org.jgroups.protocols` package.

  Note that only the base name has to be given, not the fully specified class name (e.g., UDP instead of org.jgroups.protocols.UDP).

  Each layer may have 0 or more arguments, which are specified as a list of name/value pairs in parentheses directly after the property. In the example above, the first protocol layer has 1 argument, the second 2, the third none. When a layer is created, these properties (if there are any) will be set in a layer by invoking the layer's setProperties() method

  As an example the property string below instructs JGroups to create a JChannel with protocols UDP, PING, FD and GMS:

      "UDP(mcast_addr=228.10.9.8;mcast_port=5678):PING:FD:GMS"

  The UDP protocol layer is at the bottom of the stack, and it should use mcast address 228.10.9.8. and port 5678 rather than the default IP multicast address and port. The only other argument instructs FD to output debug information while executing. Property UDP refers to a class `UDP`, which is subsequently loaded and an instance of which is created as protocol layer. If any of these classes are not found, an exception will be thrown and the construction of the stack will be aborted.

  Author:
    Bela Ban

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.Map<java.lang.String,java.lang.Object>` | `additional_data` Provides storage for arbitrary objects.
    `protected AddressGenerator` | `address_generator`
    `protected boolean` | `closed`
    `protected java.util.concurrent.ConcurrentMap<java.lang.String,java.lang.Object>` | `config`
    `protected boolean` | `connected`
    `static java.lang.String` | `DEFAULT_PROTOCOL_STACK` The default protocol stack used by the default constructor
    `protected Address` | `local_addr`
    `protected Log` | `log`
    `protected java.lang.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

      `AUTO_GETSTATE, AUTO_RECONNECT, BLOCK, channel_listeners, GET_STATE_EVENTS, LOCAL, receiver, socket_factory, SUSPECT, up_handler, VIEW`

  - ### 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(org.w3c.dom.Element properties)` Constructs a `JChannel` instance with the protocol stack configuration contained by the specified XML element.
    `JChannel(java.io.File properties)` Constructs a `JChannel` instance with the protocol stack configuration contained by the specified file.
    `JChannel(JChannel ch)` Creates a channel with the same configuration as the channel passed to this constructor.
    `JChannel(java.lang.Object properties)` Deprecated. Use the constructors with specific parameter types instead.
    `JChannel(ProtocolStackConfigurator configurator)` Constructs a `JChannel` instance with the protocol stack configuration contained by the protocol stack configurator parameter.
    `JChannel(java.lang.String properties)` Constructs a `JChannel` instance with the protocol stack configuration based upon the specified properties parameter.
    `JChannel(java.net.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, boolean close_mq)` Disconnects and closes the channel.
    `void` | `blockOk()` Called to acknowledge a block() (callback in `MembershipListener` or `BlockEvent` received from call to `receive()`).
    `protected void` | `checkClosed()` health check throws a ChannelClosed exception if the channel is closed
    `protected void` | `checkClosedOrNotConnected()`
    `void` | `close()` Destroys the channel.
    `void` | `closeMessageQueue(boolean flush_entries)`
    `void` | `connect(java.lang.String cluster_name)` Connects the channel to a group.
    `void` | `connect(java.lang.String cluster_name, Address target, java.lang.String state_id, long timeout)` Connects this channel to a group and gets a state from a specified state provider.
    `void` | `connect(java.lang.String cluster_name, Address target, java.lang.String state_id, long timeout, boolean useFlushIfPresent)` Connects this channel to a group and gets a state from a specified state provider.
    `void` | `connect(java.lang.String cluster_name, boolean useFlushIfPresent)` Connects the channel to a group.
    `void` | `disconnect()` Disconnects the channel if it is connected.
    `void` | `down(Event evt)` Sends a message through the protocol stack if the stack is available
    `java.lang.Object` | `downcall(Event evt)` Can be used instead of down() when a return value is expected.
    `protected java.util.Map<java.lang.String,java.lang.Long>` | `dumpChannelStats()`
    `java.lang.String` | `dumpQueue()`
    `java.util.Map<java.lang.String,java.lang.Object>` | `dumpStats()` Returns a map of statistics of the various protocols and of the channel itself.
    `java.util.Map<java.lang.String,java.lang.Object>` | `dumpStats(java.lang.String protocol_name)`
    `java.util.Map<java.lang.String,java.lang.Object>` | `dumpStats(java.lang.String protocol_name, java.util.List<java.lang.String> attrs)`
    `java.lang.String` | `dumpTimerQueue()`
    `void` | `enableStats(boolean stats)`
    `boolean` | `flushSupported()`
    `Address` | `getAddress()` Returns the local address of the channel (null if the channel is closed)
    `java.lang.String` | `getAddressAsString()`
    `java.lang.String` | `getAddressAsUUID()`
    `AddressGenerator` | `getAddressGenerator()` Returns the current `AddressGenerator`, or null if none is set
    `boolean` | `getAllStates(java.util.Vector targets, long timeout)` Deprecated. Not really needed - we always want to get the state from a single member, use `getState(org.jgroups.Address, long)` instead
    `java.lang.String` | `getChannelName()` Deprecated. Use `getClusterName()` instead
    `java.lang.String` | `getClusterName()` Returns the cluster name of the group of which the channel is a member.
    `java.util.Map<java.lang.String,java.lang.Object>` | `getInfo()`
    `Address` | `getLocalAddress()` Deprecated.
    `protected Log` | `getLog()`
    `java.lang.String` | `getName()` Returns the logical name of this channel if set.
    `java.lang.String` | `getName(Address member)` Returns the logical name of a given member.
    `int` | `getNumberOfTasksInTimer()`
    `int` | `getNumMessages()` Returns the number of messages that are waiting.
    `java.lang.Object` | `getOpt(int option)` returns the value of an option.
    `java.lang.String` | `getProperties()` Returns the protocol stack configuration in string format.
    `ProtocolStack` | `getProtocolStack()` Returns the protocol stack
    `long` | `getReceivedBytes()`
    `long` | `getReceivedMessages()`
    `long` | `getSentBytes()`
    `long` | `getSentMessages()`
    `boolean` | `getState(Address target, long timeout)` Retrieves a full state from the target member.
    `boolean` | `getState(Address target, java.lang.String state_id, long timeout)` Retrieves a substate (or partial state) indicated by state_id from the target member.
    `boolean` | `getState(Address target, java.lang.String state_id, long timeout, boolean useFlushIfPresent)` Retrieves a substate (or partial state) indicated by state_id from the target member.
    `protected boolean` | `getState(Address target, java.lang.String state_id, long timeout, java.util.concurrent.Callable<java.lang.Boolean> flushInvoker)` Retrieves a substate (or partial state) indicated by state_id from the target member.
    `int` | `getTimerThreads()`
    `static java.lang.String` | `getVersion()`
    `View` | `getView()` Returns the current view.
    `java.lang.String` | `getViewAsString()`
    `protected void` | `init(JChannel ch)`
    `protected void` | `init(ProtocolStackConfigurator configurator)`
    `boolean` | `isConnected()` returns true if the Connect operation has been called successfully
    `boolean` | `isOpen()` returns true if the Open operation has been called successfully
    `void` | `open()` Deprecated. With the removal of shunning, this method should not be used anymore
    `java.lang.Object` | `peek(long timeout)` Just peeks at the next message, view or block.
    `java.lang.String` | `printProtocolSpec(boolean include_properties)` Returns a pretty-printed form of all the protocols.
    `java.lang.Object` | `receive(long timeout)` Deprecated. Use a `Receiver` instead
    `void` | `resetStats()`
    `void` | `returnState(byte[] state)` Called by the application is response to receiving a `getState()` object when calling `receive()`.
    `void` | `returnState(byte[] state, java.lang.String state_id)` Returns a substate as indicated by state_id
    `void` | `send(Address dst, Address src, byte[] buf)`
    `void` | `send(Address dst, Address src, byte[] buf, int offset, int length)`
    `void` | `send(Address dst, Address src, java.io.Serializable obj)` creates a new message with the destination address, and the source address and the object as the message value
    `void` | `send(Message msg)` Sends a message through the protocol stack.
    `protected void` | `setAddress()` Generates new UUID and sets local address.
    `void` | `setAddressGenerator(AddressGenerator address_generator)` Sets the new `AddressGenerator`.
    `void` | `setInfo(java.lang.String key, java.lang.Object value)`
    `void` | `setName(java.lang.String name)` Sets the logical name for the channel.
    `void` | `setOpt(int option, java.lang.Object value)` Sets a channel option.
    `void` | `setProtocolStack(ProtocolStack stack)`
    `void` | `shutdown()` Deprecated. Use `Util.shutdown(Channel)` instead. This method will be removed in 3.0
    `boolean` | `startFlush(boolean automatic_resume)` Will perform a flush of the system, ie.
    `boolean` | `startFlush(java.util.List<Address> flushParticipants, boolean automatic_resume)` Performs a partial flush in a cluster for flush participants.
    `boolean` | `startFlush(long timeout, boolean automatic_resume)` Will perform a flush of the system, ie.
    `boolean` | `statsEnabled()`
    `void` | `stopFlush()`
    `void` | `stopFlush(java.util.List<Address> flushParticipants)`
    `protected void` | `stopStack(boolean stop, boolean destroy)`
    `java.lang.String` | `toString(boolean details)`
    `java.lang.Object` | `up(Event evt)` Callback method Called by the ProtocolStack when a message is received.

    - ### Methods inherited from class org.jgroups.Channel

      `addChannelListener, clearChannelListeners, getReceiver, getSocketFactory, getUpHandler, notifyChannelClosed, notifyChannelConnected, notifyChannelDisconnected, option2String, removeChannelListener, setChannelListener, 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 java.lang.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 java.lang.String name

    - #### connected

          protected volatile boolean connected

    - #### closed

          protected volatile boolean closed

    - #### additional_data

          protected final java.util.Map<java.lang.String,java.lang.Object> additional_data

      Provides storage for arbitrary objects. Protocols can send up CONFIG events, and all key-value pairs of a CONFIG event will be added to additional_data. On reconnect, a CONFIG event will be sent down by the channel, containing all key-value pairs of additional_data

    - #### config

          protected final java.util.concurrent.ConcurrentMap<java.lang.String,java.lang.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, tthe default configuration will be used. If false, no protocol stack will be created

    - #### JChannel

          public JChannel()
                   throws ChannelException

      Constructs a `JChannel` instance with the protocol stack specified by the `DEFAULT_PROTOCOL_STACK` member.
      Throws:
        `ChannelException` - if problems occur during the initialization of the protocol stack.

    - #### JChannel

          public JChannel(java.io.File properties)
                   throws ChannelException

      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:
        `ChannelException` - if problems occur during the configuration or initialization of the protocol stack.

    - #### JChannel

          public JChannel(org.w3c.dom.Element properties)
                   throws ChannelException

      Constructs a `JChannel` instance with the protocol stack configuration contained by the specified XML element.
      Parameters:
        `properties` - a XML element containing a JGroups XML protocol stack configuration.
      Throws:
        `ChannelException` - if problems occur during the configuration or initialization of the protocol stack.

    - #### JChannel

          public JChannel(java.net.URL properties)
                   throws ChannelException

      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:
        `ChannelException` - if problems occur during the configuration or initialization of the protocol stack.

    - #### JChannel

          public JChannel(java.lang.String properties)
                   throws ChannelException

      Constructs a `JChannel` instance with the protocol stack configuration based upon the specified properties parameter.
      Parameters:
        `properties` - an old style property string, a string representing a system resource containing a JGroups XML configuration, a string representing a URL pointing to a JGroups XML XML configuration, or a string representing a file name that contains a JGroups XML configuration.
      Throws:
        `ChannelException` - if problems occur during the configuration and initialization of the protocol stack.

    - #### JChannel

          public JChannel(ProtocolStackConfigurator configurator)
                   throws ChannelException

      Constructs a `JChannel` instance 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:
        `ChannelException` - if problems occur during the initialization of the protocol stack.

    - #### JChannel

          public JChannel(java.lang.Object properties)
                   throws ChannelException

      Deprecated. Use the constructors with specific parameter types instead.
      Creates a new JChannel with the protocol stack as defined in the properties parameter. an example of this parameter is
      "UDP:PING:FD:STABLE:NAKACK:UNICAST:FRAG:FLUSH:GMS:VIEW_ENFORCER:STATE_TRANSFER:QUEUE"
      Other examples can be found in the ./conf directory
      Parameters:
        `properties` - the protocol stack setup; if null, the default protocol stack will be used. The properties can also be a java.net.URL object or a string that is a URL spec. The JChannel will validate any URL object and String object to see if they are a URL. In case of the parameter being a url, the JChannel will try to load the xml from there. In case properties is a org.w3c.dom.Element, the ConfiguratorFactory will parse the DOM tree with the element as its root element.
      Throws:
        `ChannelException`

    - #### JChannel

          public JChannel(JChannel ch)
                   throws ChannelException

      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 any other code !
      Parameters:
        `ch` -
      Throws:
        `ChannelException`

  - ### 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 java.lang.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 java.lang.String dumpTimerQueue()

    - #### printProtocolSpec

          public java.lang.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(java.lang.String cluster_name)
                       throws ChannelException

      Connects the channel to a group. 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. This method starts the protocol stack by calling ProtocolStack.start, then it sends an Event.CONNECT event down the stack and waits for the return value. Once the call returns, the channel listeners are notified and the channel is considered connected.
      Specified by:
        `connect` in class `Channel`
      Parameters:
        `cluster_name` - A `String` denoting the group name. Cannot be null.
      Throws:
        `ChannelException` - The protocol stack cannot be started
        `ChannelClosedException` - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
      See Also:
        `Channel.disconnect()`

    - #### connect

          public void connect(java.lang.String cluster_name,
                     boolean useFlushIfPresent)
                       throws ChannelException

      Connects the channel to a group. 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. This method starts the protocol stack by calling ProtocolStack.start, then it sends an Event.CONNECT event down the stack and waits for the return value. Once the call returns, the channel listeners are notified and the channel is considered connected.
      Parameters:
        `cluster_name` - A `String` denoting the group name. Cannot be null.
      Throws:
        `ChannelException` - The protocol stack cannot be started
        `ChannelClosedException` - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.

    - #### connect

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

      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 succesion. 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.````````

      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.
        `state_id` - the substate id for partial state transfer. If null entire state will be transferred.
        `timeout` - the timeout for state transfer.
      Throws:
        `ChannelException` - The protocol stack cannot be started
        `ChannelException` - Connecting to cluster was not successful
        `ChannelClosedException` - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
        `StateTransferException` - State transfer was not successful

    - #### connect

          public void connect(java.lang.String cluster_name,
                     Address target,
                     java.lang.String state_id,
                     long timeout,
                     boolean useFlushIfPresent)
                       throws ChannelException

      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 succesion. 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 state will be fetched from coordinator, unless this channel is coordinator.
        `state_id` - the substate id for partial state transfer. If null entire state will be transferred.
        `timeout` - the timeout for state transfer.
      Throws:
        `ChannelException` - The protocol stack cannot be started
        `ChannelException` - Connecting to cluster was not successful
        `ChannelClosedException` - The channel is closed and therefore cannot be used any longer. A new channel has to be created first.
        `StateTransferException` - State transfer was not successful

    - #### disconnect

          public void disconnect()

      Disconnects the channel if it is connected. If the channel is closed, this operation is ignored
      Otherwise the following actions happen in the listed order
      1. The JChannel sends a DISCONNECT event down the protocol stack
      2. Blocks until the event has returned
      3. Sends a STOP_QUEING event down the stack
      4. Stops the protocol stack by calling ProtocolStack.stop()
      5. Notifies the listener, if the listener is available
      Specified by:
        `disconnect` in class `Channel`
      See Also:
        `Channel.connect(String)`

    - #### close

          public void close()

      Destroys the channel. After this method has been called, the channel us unusable.
      This operation will disconnect the channel and close the channel receive queue immediately
      Specified by:
        `close` in class `Channel`

    - #### shutdown

          @Deprecated
          public void shutdown()

      Deprecated. Use `Util.shutdown(Channel)` instead. This method will be removed in 3.0
      Shuts down a channel without disconnecting. To be used by tests only, don't use for application purposes
      Specified by:
        `shutdown` in class `Channel`

    - #### open

          @Deprecated
          public void open()
                    throws ChannelException

      Deprecated. With the removal of shunning, this method should not be used anymore
      Opens the channel. Note that the channel is only open, but not connected. This does the following actions:
      1. Resets the receiver queue by calling Queue.reset
      2. Sets up the protocol stack by calling ProtocolStack.setup
      3. Sets the closed flag to false
      Overrides:
        `open` in class `Channel`
      Throws:
        `ChannelException`

    - #### isOpen

          public boolean isOpen()

      returns true if the Open operation has been called successfully
      Specified by:
        `isOpen` in class `Channel`

    - #### isConnected

          public boolean isConnected()

      returns true if the Connect operation has been called successfully
      Specified by:
        `isConnected` in class `Channel`

    - #### getNumMessages

          public int getNumMessages()

      Description copied from class: `Channel`
      Returns the number of messages that are waiting. Those messages can be removed by `Channel.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).
      Overrides:
        `getNumMessages` in class `Channel`
      Returns:
        The number of messages on the queue, or -1 if the queue/channel is closed/disconnected.

    - #### dumpQueue

          public java.lang.String dumpQueue()

      Overrides:
        `dumpQueue` in class `Channel`

    - #### dumpStats

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

      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 java.util.Map<java.lang.String,java.lang.Object> dumpStats(java.lang.String protocol_name,
                                                                   java.util.List<java.lang.String> attrs)

    - #### dumpStats

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

    - #### dumpChannelStats

          protected java.util.Map<java.lang.String,java.lang.Long> dumpChannelStats()

    - #### send

          public void send(Message msg)
                    throws ChannelNotConnectedException,
                           ChannelClosedException

      Sends a message through the protocol stack. Implements the Transport interface.
      Specified by:
        `send` in interface `Transport`
      Specified by:
        `send` in class `Channel`
      Parameters:
        `msg` - the message to be sent through the protocol stack, the destination of the message is specified inside the message itself
      Throws:
        `ChannelNotConnectedException`
        `ChannelClosedException`

    - #### send

          public void send(Address dst,
                  Address src,
                  java.io.Serializable obj)
                    throws ChannelNotConnectedException,
                           ChannelClosedException

      creates a new message with the destination address, and the source address and the object as the message value
      Specified by:
        `send` in class `Channel`
      Parameters:
        `dst` - - the destination address of the message, null for all members
        `src` - - the source address of the message
        `obj` - - the value of the message
      Throws:
        `ChannelNotConnectedException`
        `ChannelClosedException`
      See Also:
        `send(org.jgroups.Message)`

    - #### send

          public void send(Address dst,
                  Address src,
                  byte[] buf)
                    throws ChannelNotConnectedException,
                           ChannelClosedException

      Specified by:
        `send` in class `Channel`
      Throws:
        `ChannelNotConnectedException`
        `ChannelClosedException`

    - #### send

          public void send(Address dst,
                  Address src,
                  byte[] buf,
                  int offset,
                  int length)
                    throws ChannelNotConnectedException,
                           ChannelClosedException

      Specified by:
        `send` in class `Channel`
      Throws:
        `ChannelNotConnectedException`
        `ChannelClosedException`

    - #### receive

          public java.lang.Object receive(long timeout)
                                   throws ChannelNotConnectedException,
                                          ChannelClosedException,
                                          TimeoutException

      Deprecated. Use a `Receiver` instead
      Blocking receive method. This method returns the object that was first received by this JChannel and that has not been received before. After the object is received, it is removed from the receive queue.
      If you only want to inspect the object received without removing it from the queue call JChannel.peek
      If no messages are in the receive queue, this method blocks until a message is added or the operation times out
      By specifying a timeout of 0, the operation blocks forever, or until a message has been received.
      Specified by:
        `receive` in interface `Transport`
      Specified by:
        `receive` in class `Channel`
      Parameters:
        `timeout` - the number of milliseconds to wait if the receive queue is empty. 0 means wait forever
      Returns:
        A Message, View, BlockEvent, SuspectEvent, GetStateEvent, SetStateEvent or ExitEvent, depending on what is on top of the internal queue.
      Throws:
        `TimeoutException` - if a timeout occured prior to a new message was received
        `ChannelNotConnectedException`
        `ChannelClosedException`
      See Also:
        `peek(long)`

    - #### peek

          public java.lang.Object peek(long timeout)
                                throws ChannelNotConnectedException,
                                       ChannelClosedException,
                                       TimeoutException

      Just peeks at the next message, view or block. Does not install new view if view is received
      Does the same thing as JChannel.receive but doesn't remove the object from the receiver queue * @deprecated Use a `Receiver` instead
      Specified by:
        `peek` in class `Channel`
      Parameters:
        `timeout` - Value in milliseconds. Value <= 0 means wait forever
      Returns:
        A Message, View, BlockEvent, SuspectEvent, GetStateEvent or SetStateEvent object, depending on what is on top of the internal queue.
      Throws:
        `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.
        `TimeoutException` - Thrown when a timeout has occurred.
      See Also:
        `Channel.receive(long)`

    - #### getView

          public View getView()

      Returns the current view.
      If the channel is not connected or if it is closed it will return null.
      Specified by:
        `getView` in class `Channel`
      Returns:
        returns the current group view, or null if the channel is closed or disconnected

    - #### getViewAsString

          public java.lang.String getViewAsString()

    - #### getVersion

          public static java.lang.String getVersion()

    - #### getLocalAddress

          @Deprecated
          public Address getLocalAddress()

      Deprecated.
      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:
        `getLocalAddress` in class `Channel`
      Returns:
        The channel's address (opaque)

    - #### getAddress

          public Address getAddress()

      Returns the local address of the channel (null if the channel is closed)
      Specified by:
        `getAddress` in class `Channel`
      Returns:
        The channel's address (opaque)

    - #### getAddressAsString

          public java.lang.String getAddressAsString()

    - #### getAddressAsUUID

          public java.lang.String getAddressAsUUID()

    - #### getName

          public java.lang.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 java.lang.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:

    - #### setName

          public 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().
      Specified by:
        `setName` in class `Channel`
      Parameters:
        `name` -

    - #### getChannelName

          public java.lang.String getChannelName()

      Deprecated. Use `getClusterName()` instead
      returns the name of the channel if the channel is not connected or if it is closed it will return null
      Specified by:
        `getChannelName` in class `Channel`
      Returns:
        The group address

    - #### getClusterName

          public java.lang.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

    - #### setOpt

          public void setOpt(int option,
                    java.lang.Object value)

      Sets a channel option. The options can be one of the following:
      - Channel.BLOCK
      - Channel.LOCAL
      - Channel.AUTO_RECONNECT
      - Channel.AUTO_GETSTATE

      There are certain dependencies between the options that you can set, I will try to describe them here.

      Option: Channel.BLOCK
      Value: java.lang.Boolean
      Result: set to true will set setOpt(VIEW, true) and the JChannel will receive BLOCKS and VIEW events
      Option: LOCAL
      Value: java.lang.Boolean
      Result: set to true the JChannel will receive messages that it self sent out.
      Option: AUTO_RECONNECT
      Value: java.lang.Boolean
      Result: set to true and the JChannel will try to reconnect when it is being closed
      Option: AUTO_GETSTATE
      Value: java.lang.Boolean
      Result: set to true, the AUTO_RECONNECT will be set to true and the JChannel will try to get the state after a close and reconnect happens

      Specified by:
        `setOpt` in class `Channel`
      Parameters:
        `option` - the parameter option Channel.VIEW, Channel.SUSPECT, etc
        `value` - the value to set for this option

    - #### getOpt

          public java.lang.Object getOpt(int option)

      returns the value of an option.
      Specified by:
        `getOpt` in class `Channel`
      Parameters:
        `option` - the option you want to see the value for
      Returns:
        the object value, in most cases java.lang.Boolean
      See Also:
        `setOpt(int, java.lang.Object)`

    - #### blockOk

          public void blockOk()

      Called to acknowledge a block() (callback in `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.
      Specified by:
        `blockOk` in class `Channel`

    - #### getState

          public boolean getState(Address target,
                         long timeout)
                           throws ChannelNotConnectedException,
                                  ChannelClosedException

      Retrieves a full state from the target member.

      State transfer is initiated by invoking getState on this channel, state receiver, and sending a GET_STATE message to a target member - state provider. State provider passes GET_STATE message to application that is using the state provider channel which in turn provides an application state to a state receiver. Upon successful installation of a state at state receiver this method returns true.

      Specified by:
        `getState` in class `Channel`
      Parameters:
        `target` - State provider. If null, coordinator is used
        `timeout` - the number of milliseconds to wait for the operation to complete successfully. 0 waits until the state has been received
      Returns:
        true if state transfer was successful, false otherwise
      Throws:
        `ChannelNotConnectedException` - if channel was not connected at the time state retrieval was initiated
        `ChannelClosedException` - if channel was closed at the time state retrieval was initiated
        `java.lang.IllegalStateException` - if one of state transfer protocols is not present in this channel
        `java.lang.IllegalStateException` - if flush is used in this channel and cluster could not be flushed
      See Also:
        `ExtendedMessageListener.getState(OutputStream)`, `ExtendedMessageListener.setState(InputStream)`, `MessageListener.getState()`, `MessageListener.setState(byte[])`

    - #### getState

          public boolean getState(Address target,
                         java.lang.String state_id,
                         long timeout)
                           throws ChannelNotConnectedException,
                                  ChannelClosedException

      Retrieves a substate (or partial state) indicated by state_id from the target member.

      State transfer is initiated by invoking getState on this channel, state receiver, and sending a GET_STATE message to a target member - state provider. State provider passes GET_STATE message to application that is using the state provider channel which in turn provides an application state to a state receiver. Upon successful installation of a state at state receiver this method returns true.

      Specified by:
        `getState` in class `Channel`
      Parameters:
        `target` - State provider. If null, coordinator is used
        `state_id` - The ID of the substate. If null, the entire state will be transferred
        `timeout` - the number of milliseconds to wait for the operation to complete successfully. 0 waits until the state has been received
      Returns:
        true if state transfer was successful, false otherwise
      Throws:
        `ChannelNotConnectedException` - if channel was not connected at the time state retrieval was initiated
        `ChannelClosedException` - if channel was closed at the time state retrieval was initiated
        `java.lang.IllegalStateException` - if one of state transfer protocols is not present in this channel
        `java.lang.IllegalStateException` - if flush is used in this channel and cluster could not be flushed
      See Also:
        `ExtendedMessageListener.getState(OutputStream)`, `ExtendedMessageListener.setState(InputStream)`, `MessageListener.getState()`, `MessageListener.setState(byte[])`

    - #### getState

          public boolean getState(Address target,
                         java.lang.String state_id,
                         long timeout,
                         boolean useFlushIfPresent)
                           throws ChannelNotConnectedException,
                                  ChannelClosedException

      Retrieves a substate (or partial state) indicated by state_id from the target member.

      State transfer is initiated by invoking getState on this channel, state receiver, and sending a GET_STATE message to a target member - state provider. State provider passes GET_STATE message to application that is using the state provider channel which in turn provides an application state to a state receiver. Upon successful installation of a state at state receiver this method returns true.

      Parameters:
        `target` - State provider. If null, coordinator is used
        `state_id` - The ID of the substate. If null, the entire state will be transferred
        `timeout` - the number of milliseconds to wait for the operation to complete successfully. 0 waits until the state has been received
        `useFlushIfPresent` - whether channel should be flushed prior to state retrieval
      Returns:
        true if state transfer was successful, false otherwise
      Throws:
        `ChannelNotConnectedException` - if channel was not connected at the time state retrieval was initiated
        `ChannelClosedException` - if channel was closed at the time state retrieval was initiated
        `java.lang.IllegalStateException` - if one of state transfer protocols is not present in this channel
        `java.lang.IllegalStateException` - if flush is used in this channel and cluster could not be flushed
      See Also:
        `ExtendedMessageListener.getState(OutputStream)`, `ExtendedMessageListener.setState(InputStream)`, `MessageListener.getState()`, `MessageListener.setState(byte[])`

    - #### getState

          protected boolean getState(Address target,
                         java.lang.String state_id,
                         long timeout,
                         java.util.concurrent.Callable<java.lang.Boolean> flushInvoker)
                              throws ChannelNotConnectedException,
                                     ChannelClosedException

      Retrieves a substate (or partial state) indicated by state_id from the target member.

      State transfer is initiated by invoking getState on this channel, state receiver, and sending a GET_STATE message to a target member - state provider. State provider passes GET_STATE message to application that is using the state provider channel which in turn provides an application state to a state receiver. Upon successful installation of a state at state receiver this method returns true.

      Parameters:
        `target` - State provider. If null, coordinator is used
        `state_id` - The ID of the substate. If null, the entire state will be transferred
        `timeout` - the number of milliseconds to wait for the operation to complete successfully. 0 waits until the state has been received
        `flushInvoker` - algorithm invoking flush
      Returns:
        true if state transfer was successful, false otherwise
      Throws:
        `ChannelNotConnectedException` - if channel was not connected at the time state retrieval was initiated
        `ChannelClosedException` - if channel was closed at the time state retrieval was initiated
        `java.lang.IllegalStateException` - if one of state transfer protocols is not present in this channel
        `java.lang.IllegalStateException` - if flush is used in this channel and cluster could not be flushed
      See Also:
        `ExtendedMessageListener.getState(OutputStream)`, `ExtendedMessageListener.setState(InputStream)`, `MessageListener.getState()`, `MessageListener.setState(byte[])`

    - #### getAllStates

          public boolean getAllStates(java.util.Vector targets,
                             long timeout)
                               throws ChannelNotConnectedException,
                                      ChannelClosedException

      Deprecated. Not really needed - we always want to get the state from a single member, use `getState(org.jgroups.Address, long)` instead
      Retrieves the current group state. Sends GET_STATE event down to STATE_TRANSFER layer. Blocks until STATE_TRANSFER sends up a GET_STATE_OK event or until `timeout` milliseconds have elapsed. The argument of GET_STATE_OK should be a vector of objects.
      Specified by:
        `getAllStates` in class `Channel`
      Parameters:
        `targets` - - the target members to receive the state from ( an Address list )
        `timeout` - - the number of milliseconds to wait for the operation to complete successfully
      Returns:
        true of the state was received, false if the operation timed out
      Throws:
        `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.

    - #### returnState

          public void returnState(byte[] state)

      Called by the application is response to receiving a `getState()` object when calling `receive()`. When the application receives a getState() message on the receive() method, it should call returnState() to reply with the state of the application
      Specified by:
        `returnState` in class `Channel`
      Parameters:
        `state` - The state of the application as a byte buffer (to send over the network).

    - #### returnState

          public void returnState(byte[] state,
                         java.lang.String state_id)

      Returns a substate as indicated by state_id
      Specified by:
        `returnState` in class `Channel`
      Parameters:
        `state` -
        `state_id` -

    - #### up

          public java.lang.Object up(Event evt)

      Callback method
      Called by the ProtocolStack when a message is received. It will be added to the message queue from which subsequent `Receive`s will dequeue it.
      Parameters:
        `evt` - the event carrying the message from the protocol stack

    - #### down

          public void 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

    - #### downcall

          public java.lang.Object downcall(Event evt)

      Description copied from class: `Channel`
      Can be used instead of down() when a return value is expected. This will be removed in 3.0 when we change the signature of down() to return Object rather than void
      Overrides:
        `downcall` in class `Channel`
      Returns:

    - #### toString

          public java.lang.String toString(boolean details)

    - #### init

          protected final void init(ProtocolStackConfigurator configurator)
                             throws ChannelException

      Throws:
        `ChannelException`

    - #### init

          protected final void init(JChannel ch)
                             throws ChannelException

      Throws:
        `ChannelException`

    - #### 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()
                              throws ChannelClosedException

      health check
      throws a ChannelClosed exception if the channel is closed
      Throws:
        `ChannelClosedException`

    - #### checkClosedOrNotConnected

          protected void checkClosedOrNotConnected()
                                            throws ChannelNotConnectedException,
                                                   ChannelClosedException

      Throws:
        `ChannelNotConnectedException`
        `ChannelClosedException`

    - #### _close

          protected void _close(boolean disconnect,
                    boolean close_mq)

      Disconnects and closes the channel. This method does the following things
      1. Calls `this.disconnect` if the disconnect parameter is true
      2. Calls `Queue.close` on mq if the close_mq parameter is true
      3. Calls `ProtocolStack.stop` on the protocol stack
      4. Calls `ProtocolStack.destroy` on the protocol stack
      5. Sets the channel closed and channel connected flags to true and false
      6. Notifies any channel listener of the channel close operation

    - #### stopStack

          protected void stopStack(boolean stop,
                       boolean destroy)

    - #### closeMessageQueue

          public final void closeMessageQueue(boolean flush_entries)

    - #### flushSupported

          public boolean flushSupported()

      Specified by:
        `flushSupported` in class `Channel`

    - #### startFlush

          public boolean startFlush(boolean automatic_resume)

      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, random sleep time backoff algorithm is employed and flush is reattempted for numberOfAttempts. Therefore this method is guaranteed to return after timeout x numberOfAttempts miliseconds.

      Specified by:
        `startFlush` in class `Channel`
      Parameters:
        `automatic_resume` - Call `stopFlush()` after the flush
      Returns:
        true if FLUSH completed within the timeout

    - #### startFlush

          public boolean startFlush(java.util.List<Address> flushParticipants,
                           boolean automatic_resume)

      Performs a partial flush in a cluster for flush participants.

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

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

      Specified by:
        `startFlush` in class `Channel`
      Parameters:
        `automatic_resume` - Call `stopFlush()` after the flush
      Returns:
        true if FLUSH completed within the timeout

    - #### startFlush

          public boolean startFlush(long timeout,
                           boolean automatic_resume)

      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, random sleep time backoff algorithm is employed and flush is reattempted for numberOfAttempts. Therefore this method is guaranteed to return after timeout x numberOfAttempts miliseconds.

      Specified by:
        `startFlush` in class `Channel`
      Parameters:
        `timeout` -
        `automatic_resume` - Call `stopFlush()` after the flush
      Returns:
        true if FLUSH completed within the timeout

    - #### stopFlush

          public void stopFlush()

      Specified by:
        `stopFlush` in class `Channel`

    - #### stopFlush

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

      Specified by:
        `stopFlush` in class `Channel`

    - #### getInfo

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

      Specified by:
        `getInfo` in class `Channel`

    - #### setInfo

          public void setInfo(java.lang.String key,
                     java.lang.Object value)

      Specified by:
        `setInfo` in class `Channel`

Copyright © 1998-2009 Bela Ban / Red Hat. All Rights Reserved.