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 MessageListener.receive(Message) callback, or extending ReceiverAdapter and overriding the ReceiverAdapter.receive(Message) method.

    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

      • flush_supported

        protected volatile boolean flush_supported

      • sent_msgs

        protected long sent_msgs

      • received_msgs

        protected long received_msgs

      • sent_bytes

        protected long sent_bytes

      • received_bytes

        protected long received_bytes

      • 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
        Throws:
        java.lang.Exception

      • JChannel

        public JChannel​(java.net.URL properties)
         throws java.lang.Exception
        Constructs a JChannel instance with the protocol stack configuration indicated by the specified URL.
        Parameters:
        properties - A URL pointing to a JGroups XML protocol stack configuration.
        Throws:
        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 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:
        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

      • JChannel

        public JChannel​(JChannel ch)
         throws java.lang.Exception
        Creates a channel with the same configuration as the channel passed to this constructor. This is used by testing code, and should not be used by clients!
        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)

      • flushSupported

        public boolean flushSupported()

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

      • getSentMessages

        public long getSentMessages()

      • getSentBytes

        public long getSentBytes()

      • getReceivedMessages

        public long getReceivedMessages()

      • getReceivedBytes

        public long getReceivedBytes()

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

      • resetStats

        public JChannel resetStats()

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

      • dumpChannelStats

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

      • 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

        protected JChannel connect​(java.lang.String cluster_name,
                           boolean useFlushIfPresent)
                    throws java.lang.Exception
        Connects the channel to a cluster.
        Throws:
        java.lang.Exception

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

      • connect

        public JChannel connect​(java.lang.String cluster_name,
                        Address target,
                        long timeout,
                        boolean useFlushIfPresent)
                 throws java.lang.Exception
        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:
        java.lang.Exception - The protocol stack cannot be started, or the JOIN failed
        java.lang.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:
        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,
                         boolean useFlushIfPresent)
                  throws java.lang.Exception
        Retrieves state from the target member. See getState(Address,long) for details
        Throws:
        java.lang.Exception

      • startFlush

        public JChannel startFlush​(boolean automatic_resume)
                    throws java.lang.Exception
        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:
        java.lang.Exception

      • startFlush

        public JChannel startFlush​(java.util.List<Address> flushParticipants,
                           boolean automatic_resume)
                    throws java.lang.Exception
        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:
        java.lang.Exception

      • stopFlush

        public JChannel stopFlush()
        Stops the current flush round. Cluster members are unblocked and allowed to send new and pending messages

      • stopFlush

        public JChannel stopFlush​(java.util.List<Address> flushParticipants)
        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 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)

      • 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​(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 void cleanup()

      • getState

        protected JChannel getState​(Address target,
                            long timeout,
                            java.util.concurrent.Callable<java.lang.Boolean> flushInvoker)
                     throws java.lang.Exception
        Throws:
        java.lang.Exception

      • invokeCallback

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

      • init

        protected final JChannel init​(JChannel ch)
                       throws java.lang.Exception
        Throws:
        java.lang.Exception

      • 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 and sets local_addr. Sends down a REMOVE_ADDRESS (if existing address was present) and a SET_LOCAL_ADDRESS

      • generateAddress

        protected Address generateAddress()

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