Package org.jgroups

Class 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.

    Version:
    $Id: JChannel.java,v 1.158.2.25 2009/03/30 12:35:18 belaban Exp $
    Author:
    Bela Ban
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        JChannel()
      Constructs a JChannel instance with the protocol stack specified by the DEFAULT_PROTOCOL_STACK member.
      protected JChannel​(boolean no_op)
      Used by subclass to create a JChannel without a protocol stack, don't use as application programmer
        JChannel​(java.io.File properties)
      Constructs a JChannel instance with the protocol stack configuration contained by the specified file.
        JChannel​(java.lang.Object properties)
      Deprecated.
      Use the constructors with specific parameter types instead.
        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.
        JChannel​(ProtocolStackConfigurator configurator)
      Constructs a JChannel instance with the protocol stack configuration contained by the protocol stack configurator parameter.
        JChannel​(org.w3c.dom.Element properties)
      Constructs a JChannel instance with the protocol stack configuration contained by the specified XML element.
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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 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.lang.String dumpTimerQueue()  
      void enableStats​(boolean stats)  
      boolean flushSupported()  
      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()
      returns the local address of the channel returns null if the channel is closed
      java.lang.String getLocalAddressAsString()  
      protected org.apache.commons.logging.Log getLog()  
      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()  
      View getView()
      Returns the current view.
      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()
      Opens the channel.
      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, 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.
      void setInfo​(java.lang.String key, java.lang.Object value)  
      void setOpt​(int option, java.lang.Object value)
      Sets a channel option.
      void shutdown()
      Shuts down the channel without disconnecting
      boolean startFlush​(boolean automatic_resume)
      Will perform a flush of the system, ie.
      boolean startFlush​(long timeout, 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 statsEnabled()  
      void stopFlush()  
      void stopFlush​(java.util.List<Address> flushParticipants)  
      protected void stopStack​(boolean disconnect, 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 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
      • closer

        protected org.jgroups.JChannel.CloserThread closer
        Thread responsible for closing a channel and potentially reconnecting to it (e.g., when shunned).
      • 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
      • info

        protected final java.util.concurrent.ConcurrentMap<java.lang.String,​java.lang.Object> info
      • log

        protected final org.apache.commons.logging.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

        protected JChannel​(boolean no_op)
        Used by subclass to create a JChannel without a protocol stack, don't use as application programmer
      • 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
    • Method Detail

      • getProtocolStack

        public ProtocolStack getProtocolStack()
        Returns the protocol stack. Currently used by Debugger. Specific to JChannel, therefore not visible in Channel
      • getLog

        protected org.apache.commons.logging.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"
      • 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,
                            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
      • 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

        public void shutdown()
        Shuts down the channel without disconnecting
        Specified by:
        shutdown in class Channel
      • open

        public void open()
                  throws ChannelException
        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)
      • dumpChannelStats

        protected java.util.Map<java.lang.String,​java.lang.Long> dumpChannelStats()
      • 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
        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
      • getLocalAddress

        public Address getLocalAddress()
        returns the local address of the channel returns null if the channel is closed
        Specified by:
        getLocalAddress in class Channel
        Returns:
        The channel's address. Generated by the underlying transport, and opaque. Addresses can be used as destination in the Send operation.
      • getLocalAddressAsString

        public java.lang.String getLocalAddressAsString()
      • 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
      • 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
        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)
                         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 Receives 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)
      • _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 disconnect,
                                 boolean destroy)
      • closeMessageQueue

        public final void closeMessageQueue​(boolean flush_entries)
      • 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