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
Author:
Bela Ban
  • Field Details

  • 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

    • log

      public Log log()
    • admin

      public Admin admin()
    • 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()
    • stack

      public JChannel stack(ProtocolStack st)
    • getUpHandler

      public UpHandler getUpHandler()
    • setUpHandler

      public JChannel setUpHandler(UpHandler h)
    • getDiscardOwnMessages

      public boolean getDiscardOwnMessages()
    • setDiscardOwnMessages

      public JChannel setDiscardOwnMessages(boolean flag)
    • probeHandler

      public DiagnosticsHandler.ProbeHandler probeHandler()
    • probeHandler

      public JChannel probeHandler(DiagnosticsHandler.ProbeHandler h)
    • stack

      public JChannel stack(ProtocolStack st, boolean delete_old_stack)
    • 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

      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 invokes connect and getState methods. 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, the 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
    • 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.
      Parameters:
      dst - the destination address. If null, the message will be sent to all cluster nodes (= cluster 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 smaller thanq 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 is received by 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, or 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:
    • 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()
    • 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)