Package org.jgroups

Class JChannel

java.lang.Object
org.jgroups.JChannel
All Implemented Interfaces:
Closeable, AutoCloseable
Direct Known Subclasses:
ForkChannel
public class JChannel extends Object implements Closeable
A channel represents a group communication endpoint (like a socket). An application joins a cluster by connecting the channel to a cluster name and leaves it by disconnecting. Messages sent over the channel are received by all cluster members that are connected to the same cluster (that is, all members that have the same cluster name).

The state machine for a channel is as follows: a channel is created (unconnected). The channel is connected to a cluster (connected). Messages can now be sent and received. The channel is disconnected from the cluster (unconnected). The channel could now be connected to a different cluster 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 cluster members using the send method and messages can be received by setting a Receiver in setReceiver(Receiver) and implementing the Receiver.receive(Message) callback.

Since:
2.0

  • Field Details

    • receiver

      protected Receiver receiver

    • local_addr

      protected Address local_addr

    • name

      protected String name

    • cluster_name

      protected String cluster_name

    • view

      protected View view

    • state

      protected volatile JChannel.State state

    • prot_stack

      protected ProtocolStack prot_stack

    • up_handler

      protected UpHandler up_handler

    • channel_listeners

      protected Set<ChannelListener> channel_listeners

    • log

      protected final Log log

    • address_generators

      protected List<AddressGenerator> address_generators

    • state_promise

      protected final Promise<StateTransferResult> state_promise

    • state_transfer_supported

      protected boolean state_transfer_supported

    • flush_supported

      protected volatile boolean flush_supported

    • probe_handler

      protected final DiagnosticsHandler.ProbeHandler probe_handler

    • stats

      protected boolean stats

    • discard_own_messages

      protected boolean discard_own_messages

  • Constructor Details

    • 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 config is used. If false, no protocol stack is created

    • JChannel

      public JChannel() throws Exception
      Creates a JChannel with the default stack
      Throws:
      Exception

    • 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 or a URL pointing to an XML configuration
      Throws:
      Exception

    • 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. It is the caller's resposibility to close the input stream after the constructor returns
      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 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

    • JChannel

      public JChannel(Protocol... protocols) throws Exception
      Creates a channel from an array of protocols. Note that after a close(), the protocol list should not be reused, ie. new JChannel(protocols) would reuse the same protocol list, and this might lead to problems!
      Parameters:
      protocols - The list of protocols, from bottom to top, ie. the first protocol in the list is the transport, the last the top protocol
      Throws:
      Exception

    • JChannel

      public JChannel(List<Protocol> protocols) throws Exception
      Creates a channel from a list of protocols. Note that after a close(), the protocol list should not be reused, ie. new JChannel(protocols) would reuse the same protocol list, and this might lead to problems !
      Parameters:
      protocols - The list of protocols, from bottom to top, ie. the first protocol in the list is the transport, the last the top protocol
      Throws:
      Exception

  • Method Details

    • getReceiver

      public Receiver getReceiver()

    • setReceiver

      public JChannel setReceiver(Receiver r)

    • receiver

      public JChannel receiver(Receiver r)

    • getAddress

      public Address getAddress()

    • address

      public Address address()

    • getName

      public String getName()

    • name

      public String name()

    • name

      public JChannel name(String name)

    • clusterName

      public String clusterName()

    • getView

      public View getView()

    • view

      public View view()

    • getProtocolStack

      public ProtocolStack getProtocolStack()

    • stack

      public ProtocolStack stack()

    • getUpHandler

      public UpHandler getUpHandler()

    • setUpHandler

      public JChannel setUpHandler(UpHandler h)

    • getStats

      public boolean getStats()

    • stats

      public boolean stats()

    • setStats

      public JChannel setStats(boolean stats)

    • stats

      public JChannel stats(boolean stats)

    • getDiscardOwnMessages

      public boolean getDiscardOwnMessages()

    • setDiscardOwnMessages

      public JChannel setDiscardOwnMessages(boolean flag)

    • flushSupported

      @Deprecated(since="5.3.5", forRemoval=true) public boolean flushSupported()
      Deprecated, for removal: This API element is subject to removal in a future version.

    • getAddressAsString

      public String getAddressAsString()

    • getAddressAsUUID

      public String getAddressAsUUID()

    • setName

      public JChannel setName(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 must be called before calling connect()

    • getClusterName

      public String getClusterName()

    • getViewAsString

      public String getViewAsString()

    • getState

      public String getState()

    • isOpen

      public boolean isOpen()

    • isConnected

      public boolean isConnected()

    • isConnecting

      public boolean isConnecting()

    • isClosed

      public boolean isClosed()

    • getVersion

      public static String getVersion()

    • addChannelListener

      public JChannel addChannelListener(ChannelListener listener)
      Adds a ChannelListener that will be notified when a connect, disconnect or close occurs

    • removeChannelListener

      public JChannel removeChannelListener(ChannelListener listener)

    • clearChannelListeners

      public JChannel clearChannelListeners()

    • addAddressGenerator

      public JChannel addAddressGenerator(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

    • removeAddressGenerator

      public boolean removeAddressGenerator(AddressGenerator address_generator)

    • getProperties

      public String getProperties()
      Returns the protocol stack configuration in string format. An example of this property is 
      "UDP:PING:FDALL:STABLE:NAKACK2:UNICAST3:FRAG2:GMS"

    • printProtocolSpec

      public String printProtocolSpec(boolean include_props)
      Dumps all protocols in string format. If include_props is set, the attrs of each protocol are also printed

    • dumpStats

      public Map<String,Map<String,Object>> dumpStats()
      Returns a map of statistics of the various protocols and of the channel itself

    • dumpStats

      public Map<String,Map<String,Object>> dumpStats(String protocol_name, List<String> attrs)

    • dumpStats

      public Map<String,Map<String,Object>> dumpStats(String protocol_name)

    • connect

      public JChannel connect(String cluster_name) throws Exception
      Joins the cluster. The application is now able to receive messages from cluster members, views and to send messages to (all or single) cluster members. This is a no-op if already connected.

      All channels connecting to the same cluster name form a cluster; messages sent to the cluster will be received by all cluster members.

      Parameters:
      cluster_name - The name of the cluster to join
      Throws:
      Exception - The protocol stack cannot be started
      IllegalStateException - The channel is closed

    • connect

      @Deprecated(since="5.3.5", forRemoval=true) protected JChannel connect(String cluster_name, boolean useFlushIfPresent) throws Exception
      Deprecated, for removal: This API element is subject to removal in a future version.
      Connects the channel to a cluster.
      Throws:
      Exception

    • connect

      public JChannel connect(String cluster_name, Address target, long timeout) throws Exception
      Joins the cluster and gets the 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:
      Exception - Connecting to the cluster or state transfer was not successful
      IllegalStateException - The channel is closed and therefore cannot be used

    • connect

      @Deprecated(since="5.3.5", forRemoval=true) public JChannel connect(String cluster_name, Address target, long timeout, boolean useFlushIfPresent) throws Exception
      Deprecated, for removal: This API element is subject to removal in a future version.
      Joins the cluster 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 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 JChannel disconnect()
      Leaves the cluster (disconnects the channel if it is connected). If the channel is closed or disconnected, this operation is ignored. The channel can then be used to join the same or a different cluster again.
      See Also:

    • close

      public void close()
      Destroys the channel and its associated resources (e.g. the protocol stack). After a channel has been closed, invoking methods on it will throw a ChannelClosed exception (or results in a null operation). It is a no-op if the channel is already closed.

      If the channel is connected to a cluster, disconnect() will be called first.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • send

      public JChannel send(Message msg) throws Exception
      Sends a message. The message contains
      1. a destination address (Address). A null address sends the message to all cluster members.
      2. a source address. Can be left empty as it will be assigned automatically
      3. a byte buffer. The message contents.
      4. several additional fields. They can be used by application programs (or patterns). E.g. a message ID, flags etc
      Parameters:
      msg - the message to be sent. Destination and buffer should be set. A null destination means to send to all group members.
      Throws:
      IllegalStateException - thrown if the channel is disconnected or closed
      Exception

    • send

      public JChannel send(Address dst, Object obj) throws Exception
      Helper method to create a Message with given parameters and invoke send(Message).
      Parameters:
      dst - destination address for the message. If null, the message will be sent to all cluster 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 JChannel send(Address dst, byte[] buf) throws Exception
      Sends a message. See send(Address,byte[],int,int) for details
      Parameters:
      dst - destination address for the message. If null, the message will be sent to all cluster members
      buf - buffer message payload
      Throws:
      Exception - exception thrown if the message sending was not successful

    • send

      public JChannel send(Address dst, byte[] buf, int offset, int length) throws Exception
      Sends a message to a destination. * @param dst the destination address. If null, the message will be sent to all cluster nodes (= cluster members)
      Parameters:
      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 - thrown if send() failed

    • getState

      public JChannel getState(Address target, long timeout) throws Exception
      Retrieves the full state from the target member.

      The state transfer is initiated by invoking getState() on this channel. The state provider in turn invokes the Receiver.getState(java.io.OutputStream) callback and sends the state to this node, the state receiver. After the state arrives at the state receiver, the Receiver.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 forever 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:

    • getState

      @Deprecated(since="5.3.5", forRemoval=true) public JChannel getState(Address target, long timeout, boolean useFlushIfPresent) throws Exception
      Deprecated, for removal: This API element is subject to removal in a future version.
      Retrieves state from the target member. See getState(Address,long) for details
      Throws:
      Exception

    • startFlush

      @Deprecated(since="5.3.5", forRemoval=true) public JChannel startFlush(boolean automatic_resume) throws Exception
      Deprecated, for removal: This API element is subject to removal in a future version.
      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:
      Exception

    • startFlush

      @Deprecated(since="5.3.5", forRemoval=true) public JChannel startFlush(List<Address> flushParticipants, boolean automatic_resume) throws Exception
      Deprecated, for removal: This API element is subject to removal in a future version.
      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:
      Exception

    • stopFlush

      @Deprecated(since="5.3.5", forRemoval=true) public JChannel stopFlush()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Stops the current flush round. Cluster members are unblocked and allowed to send new and pending messages

    • stopFlush

      @Deprecated(since="5.3.5", forRemoval=true) public JChannel stopFlush(List<Address> flushParticipants)
      Deprecated, for removal: This API element is subject to removal in a future version.
      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

    • down

      public Object down(Event evt)
      Sends an event down the protocol stack. Note that - contrary to send(Message), if the event is a message, no checks are performed whether the channel is closed or disconnected. Note that this method is not typically used by applications.
      Parameters:
      evt - the message to send down, encapsulated in an event

    • down

      public Object down(Message msg)

    • down

      public CompletableFuture<Object> down(Message msg, boolean async)
      Sends a message down asynchronously. The sending is executed in the transport's thread pool. If the pool is full and the message is marked as Message.TransientFlag.DONT_BLOCK, then it will be dropped, otherwise it will be sent on the caller's thread.
      Parameters:
      msg - The message to be sent
      async - Whether to send the message asynchronously
      Returns:
      A CompletableFuture of the result (or 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

    • up

      public Object up(Message msg)

    • up

      public JChannel up(MessageBatch batch)
      Callback invoked by the protocol stack to deliver a message batch

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toString

      public String toString(boolean details)

    • _preConnect

      protected boolean _preConnect(String cluster_name) throws Exception
      Throws:
      Exception

    • _connect

      protected JChannel _connect(Event evt) throws Exception
      Throws:
      Exception

    • cleanup

      protected JChannel cleanup()

    • getState

      protected JChannel getState(Address target, long timeout, Callable<Boolean> flushInvoker) throws Exception
      Throws:
      Exception

    • invokeCallback

      protected Object invokeCallback(int type, Object arg)

    • init

      protected final JChannel init(ProtocolStackConfigurator configurator) throws Exception
      Throws:
      Exception

    • init

      protected JChannel init()
      Initializes all variables. Used after close() or disconnect(), to be ready for new connect()

    • startStack

      protected JChannel startStack(String cluster_name) throws Exception
      Throws:
      Exception

    • setAddress

      protected JChannel setAddress()
      Generates local_addr. Sends down a REMOVE_ADDRESS (if existing address was present) and a SET_LOCAL_ADDRESS

    • generateAddress

      protected Address generateAddress(String name)

    • checkClosed

      protected JChannel checkClosed()

    • checkClosedOrNotConnected

      protected JChannel checkClosedOrNotConnected()

    • _close

      protected JChannel _close(boolean disconnect)

    • stopStack

      protected JChannel stopStack(boolean stop, boolean destroy)

    • determineCoordinator

      protected Address determineCoordinator()

    • notifyChannelConnected

      protected JChannel notifyChannelConnected(JChannel c)

    • notifyChannelDisconnected

      protected JChannel notifyChannelDisconnected(JChannel c)

    • notifyChannelClosed

      protected JChannel notifyChannelClosed(JChannel c)

    • notifyListeners

      protected JChannel notifyListeners(Consumer<ChannelListener> func, String msg)