Package org.jgroups

Class JChannel

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    Direct Known Subclasses:
    ForkChannel
    public class JChannel
extends java.lang.Object
implements java.io.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 Detail

      • local_addr

        protected Address local_addr

      • name

        protected java.lang.String name

      • cluster_name

        protected java.lang.String cluster_name

      • view

        protected View view

      • channel_listeners

        protected java.util.Set<ChannelListener> channel_listeners

      • log

        protected final Log log

      • address_generators

        protected java.util.List<AddressGenerator> address_generators

      • state_transfer_supported

        protected boolean state_transfer_supported

      • stats

        protected boolean stats

      • discard_own_messages

        protected boolean discard_own_messages

    • Constructor Detail

      • JChannel

        public JChannel​(boolean create_protocol_stack)
        Creates a JChannel without a protocol stack; used for programmatic creation of channel and protocol stack
        Parameters:
        create_protocol_stack - If true, the default config is used. If false, no protocol stack is created

      • JChannel

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

      • JChannel

        public JChannel​(java.lang.String props)
         throws java.lang.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:
        java.lang.Exception

      • JChannel

        public JChannel​(java.io.InputStream input)
         throws java.lang.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:
        java.lang.Exception

      • JChannel

        public JChannel​(ProtocolStackConfigurator configurator)
         throws java.lang.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:
        java.lang.Exception

      • JChannel

        public JChannel​(Protocol... protocols)
         throws java.lang.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:
        java.lang.Exception

      • JChannel

        public JChannel​(java.util.List<Protocol> protocols)
         throws java.lang.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:
        java.lang.Exception

    • Method Detail

      • getReceiver

        public Receiver getReceiver()

      • getAddress

        public Address getAddress()

      • address

        public Address address()

      • getName

        public java.lang.String getName()

      • name

        public java.lang.String name()

      • name

        public JChannel name​(java.lang.String name)

      • clusterName

        public java.lang.String clusterName()

      • getView

        public View getView()

      • view

        public View view()

      • getUpHandler

        public UpHandler getUpHandler()

      • 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)

      • getAddressAsString

        public java.lang.String getAddressAsString()

      • getAddressAsUUID

        public java.lang.String getAddressAsUUID()

      • setName

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

      • getClusterName

        public java.lang.String getClusterName()

      • getViewAsString

        public java.lang.String getViewAsString()

      • getState

        public java.lang.String getState()

      • isOpen

        public boolean isOpen()

      • isConnected

        public boolean isConnected()

      • isConnecting

        public boolean isConnecting()

      • isClosed

        public boolean isClosed()

      • getVersion

        public static java.lang.String getVersion()

      • addChannelListener

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

      • 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 java.lang.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 java.lang.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 java.util.Map<java.lang.String,​java.util.Map<java.lang.String,​java.lang.Object>> dumpStats()
        Returns a map of statistics of the various protocols and of the channel itself

      • dumpStats

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

      • connect

        public JChannel connect​(java.lang.String cluster_name)
                 throws java.lang.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:
        java.lang.Exception - The protocol stack cannot be started
        java.lang.IllegalStateException - The channel is closed

      • connect

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

      • disconnect

        public 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:
        connect(String)

      • 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 java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable

      • send

        public JChannel send​(Message msg)
              throws java.lang.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:
        java.lang.IllegalStateException - thrown if the channel is disconnected or closed
        java.lang.Exception

      • send

        public JChannel send​(Address dst,
                     java.lang.Object obj)
              throws java.lang.Exception
        Helper method to create a Message with given parameters and invoke send(Message).
        Parameters:
        dst - destination address for 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:
        java.lang.Exception - exception thrown if message sending was not successful

      • send

        public JChannel send​(Address dst,
                     byte[] buf)
              throws java.lang.Exception
        Sends a message. See send(Address,byte[],int,int) for details
        Parameters:
        dst - destination address for the message. If null, the message will be sent to all cluster members
        buf - buffer message payload
        Throws:
        java.lang.Exception - exception thrown if the message sending was not successful

      • send

        public JChannel send​(Address dst,
                     byte[] buf,
                     int offset,
                     int length)
              throws java.lang.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:
        java.lang.Exception - thrown if send() failed

      • getState

        public JChannel getState​(Address target,
                         long timeout)
                  throws java.lang.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:
        java.lang.IllegalStateException - the channel was closed or disconnected, or the flush (if present) failed
        StateTransferException - raised if there was a problem during the state transfer
        java.lang.Exception
        See Also:
        Receiver.getState(java.io.OutputStream), Receiver.setState(java.io.InputStream)

      • down

        public java.lang.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 java.lang.Object down​(Message msg)

      • down

        public java.util.concurrent.CompletableFuture<java.lang.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 java.lang.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 java.lang.Object up​(Message msg)

      • up

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

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • toString

        public java.lang.String toString​(boolean details)

      • _preConnect

        protected boolean _preConnect​(java.lang.String cluster_name)
                       throws java.lang.Exception
        Throws:
        java.lang.Exception

      • _connect

        protected JChannel _connect​(Event evt)
                     throws java.lang.Exception
        Throws:
        java.lang.Exception

      • cleanup

        protected JChannel cleanup()

      • invokeCallback

        protected java.lang.Object invokeCallback​(int type,
                                          java.lang.Object arg)

      • init

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

      • startStack

        protected JChannel startStack​(java.lang.String cluster_name)
                       throws java.lang.Exception
        Throws:
        java.lang.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​(java.lang.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)

      • notifyListeners

        protected JChannel notifyListeners​(java.util.function.Consumer<ChannelListener> func,
                                   java.lang.String msg)