Interface Channel

  • All Known Subinterfaces:
    ManagedChannel
    All Known Implementing Classes:
    GroupChannel

    public interface Channel
    Channel interface
    A channel is a representation of a group of nodes all participating in some sort of communication with each other.
    The channel is the main API class for Tribes, this is essentially the only class that an application needs to be aware of. Through the channel the application can:
    1. send messages
    2. receive message (by registering a ChannelListener
    3. get all members of the group getMembers()
    4. receive notifications of members added and members disappeared by registering a MembershipListener

    The channel has 5 major components:
    1. Data receiver, with a built in thread pool to receive messages from other peers
    2. Data sender, an implementation for sending data using NIO or java.io
    3. Membership listener,listens for membership broadcasts
    4. Membership broadcaster, broadcasts membership pings.
    5. Channel interceptors, the ability to manipulate messages as they are sent or arrive

    The channel layout is:
    
      ChannelListener_1..ChannelListener_N MembershipListener_1..MembershipListener_N [Application Layer]
                \          \                  /                   /
                 \          \                /                   /
                  \          \              /                   /
                   \          \            /                   /
                    \          \          /                   /
                     \          \        /                   /
                      ---------------------------------------
                                      |
                                      |
                                   Channel
                                      |
                             ChannelInterceptor_1
                                      |                                               [Channel stack]
                             ChannelInterceptor_N
                                      |
                                 Coordinator (implements MessageListener,MembershipListener,ChannelInterceptor)
                              --------------------
                             /        |           \
                            /         |            \
                           /          |             \
                          /           |              \
                         /            |               \
               MembershipService ChannelSender ChannelReceiver                        [IO layer]
     
    For example usage @see org.apache.catalina.tribes.group.GroupChannel
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int DEFAULT
      Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
      DEFAULT - starts or stops all components in the channel
      static int MBR_RX_SEQ
      Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
      MBR_RX_SEQ - starts or stops the membership listener.
      static int MBR_TX_SEQ
      Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
      MBR_TX_SEQ - starts or stops the membership broadcaster.
      static int SEND_OPTIONS_ASYNCHRONOUS
      Send options, when a message is sent, it can have an option flag to trigger certain behavior.
      static int SEND_OPTIONS_BYTE_MESSAGE
      Send options, when a message is sent, it can have an option flag to trigger certain behavior.
      static int SEND_OPTIONS_DEFAULT
      Send options, when a message is sent, it can have an option flag to trigger certain behavior.
      static int SEND_OPTIONS_MULTICAST
      Send options.
      static int SEND_OPTIONS_SECURE
      Send options, when a message is sent, it can have an option flag to trigger certain behavior.
      static int SEND_OPTIONS_SYNCHRONIZED_ACK
      Send options, when a message is sent, it can have an option flag to trigger certain behavior.
      static int SEND_OPTIONS_UDP
      Send options.
      static int SEND_OPTIONS_USE_ACK
      Send options, when a message is sent, it can have an option flag to trigger certain behavior.
      static int SND_RX_SEQ
      Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
      SND_RX_SEQ - starts or stops the data receiver.
      static int SND_TX_SEQ
      Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
      SND_TX_SEQ - starts or stops the data sender.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addChannelListener​(ChannelListener listener)
      Add a channel listener, this is a callback object when messages are received
      If the channel listener implements the Heartbeat interface the heartbeat() method will be invoked when the heartbeat runs on the channel
      void addInterceptor​(ChannelInterceptor interceptor)
      Adds an interceptor to the channel message chain.
      void addMembershipListener​(MembershipListener listener)
      Add a membership listener, will get notified when a new member joins, leaves or crashes
      If the membership listener implements the Heartbeat interface the heartbeat() method will be invoked when the heartbeat runs on the channel
      Member getLocalMember​(boolean incAlive)
      Return the member that represents this node.
      Member getMember​(Member mbr)
      Returns the member from the membership service with complete and recent data.
      Member[] getMembers()
      Get all current group members
      String getName()
      Return the name of this channel.
      static String getSendOptionsAsString​(int input)
      Translates an integer value of SendOptions to its human-friendly comma separated value list for use in JMX and such.
      static int getSendOptionValue​(String opt)
      Translates the name of an option to its integer value.
      ScheduledExecutorService getUtilityExecutor()
      Return executor that can be used for utility tasks.
      boolean hasMembers()
      Returns true if there are any members in the group, this call is the same as getMembers().length > 0
      void heartbeat()
      Sends a heart beat through the interceptor stacks Use this method to alert interceptors and other components to clean up garbage, timed out messages etc.
      If you application has a background thread, then you can save one thread, by configuring your channel to not use an internal heartbeat thread and invoking this method.
      static int parseSendOptions​(String input)
      Translates a comma separated list of option names to their bitwise-ORd value
      void removeChannelListener​(ChannelListener listener)
      remove a channel listener, listeners are removed based on Object.hashCode and Object.equals
      void removeMembershipListener​(MembershipListener listener)
      remove a membership listener, listeners are removed based on Object.hashCode and Object.equals
      UniqueId send​(Member[] destination, Serializable msg, int options)
      Send a message to one or more members in the cluster
      UniqueId send​(Member[] destination, Serializable msg, int options, ErrorHandler handler)
      Send a message to one or more members in the cluster
      void setHeartbeat​(boolean enable)
      Enables or disables internal heartbeat.
      void setName​(String name)
      Set the name of this channel
      void setUtilityExecutor​(ScheduledExecutorService utilityExecutor)
      Set the executor that can be used for utility tasks.
      void start​(int svc)
      Starts up the channel.
      void stop​(int svc)
      Shuts down the channel.
    • Field Detail

      • DEFAULT

        static final int DEFAULT
        Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
        DEFAULT - starts or stops all components in the channel
        See Also:
        start(int), stop(int), Constant Field Values
      • SND_RX_SEQ

        static final int SND_RX_SEQ
        Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
        SND_RX_SEQ - starts or stops the data receiver. Start means opening a server socket in case of a TCP implementation
        See Also:
        start(int), stop(int), Constant Field Values
      • SND_TX_SEQ

        static final int SND_TX_SEQ
        Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
        SND_TX_SEQ - starts or stops the data sender. This should not open any sockets, as sockets are opened on demand when a message is being sent
        See Also:
        start(int), stop(int), Constant Field Values
      • MBR_RX_SEQ

        static final int MBR_RX_SEQ
        Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
        MBR_RX_SEQ - starts or stops the membership listener. In a multicast implementation this will open a datagram socket and join a group and listen for membership messages members joining
        See Also:
        start(int), stop(int), Constant Field Values
      • MBR_TX_SEQ

        static final int MBR_TX_SEQ
        Start and stop sequences can be controlled by these constants This allows you to start separate components of the channel
        MBR_TX_SEQ - starts or stops the membership broadcaster. In a multicast implementation this will open a datagram socket and join a group and broadcast the local member information
        See Also:
        start(int), stop(int), Constant Field Values
      • SEND_OPTIONS_BYTE_MESSAGE

        static final int SEND_OPTIONS_BYTE_MESSAGE
        Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
        However, there are five default flags that every channel implementation must implement
        SEND_OPTIONS_BYTE_MESSAGE - The message is a pure byte message and no marshaling or unmarshaling will be performed.
        See Also:
        send(Member[], Serializable , int), send(Member[], Serializable, int, ErrorHandler), Constant Field Values
      • SEND_OPTIONS_USE_ACK

        static final int SEND_OPTIONS_USE_ACK
        Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
        However, there are five default flags that every channel implementation must implement
        SEND_OPTIONS_USE_ACK - Message is sent and an ACK is received when the message has been received by the recipient
        If no ack is received, the message is not considered successful
        See Also:
        send(Member[], Serializable , int), send(Member[], Serializable, int, ErrorHandler), Constant Field Values
      • SEND_OPTIONS_SYNCHRONIZED_ACK

        static final int SEND_OPTIONS_SYNCHRONIZED_ACK
        Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
        However, there are five default flags that every channel implementation must implement
        SEND_OPTIONS_SYNCHRONIZED_ACK - Message is sent and an ACK is received when the message has been received and processed by the recipient
        If no ack is received, the message is not considered successful
        See Also:
        send(Member[], Serializable , int), send(Member[], Serializable, int, ErrorHandler), Constant Field Values
      • SEND_OPTIONS_ASYNCHRONOUS

        static final int SEND_OPTIONS_ASYNCHRONOUS
        Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
        However, there are five default flags that every channel implementation must implement
        SEND_OPTIONS_ASYNCHRONOUS - Message is sent and an ACK is received when the message has been received and processed by the recipient
        If no ack is received, the message is not considered successful
        See Also:
        send(Member[], Serializable , int), send(Member[], Serializable, int, ErrorHandler), Constant Field Values
      • SEND_OPTIONS_SECURE

        static final int SEND_OPTIONS_SECURE
        Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
        However, there are five default flags that every channel implementation must implement
        SEND_OPTIONS_SECURE - Message is sent over an encrypted channel
        See Also:
        send(Member[], Serializable , int), send(Member[], Serializable, int, ErrorHandler), Constant Field Values
      • SEND_OPTIONS_DEFAULT

        static final int SEND_OPTIONS_DEFAULT
        Send options, when a message is sent, it can have an option flag to trigger certain behavior. Most flags are used to trigger channel interceptors as the message passes through the channel stack.
        However, there are five default flags that every channel implementation must implement
        SEND_OPTIONS_DEFAULT - the default sending options, just a helper variable.
        The default is int SEND_OPTIONS_DEFAULT = SEND_OPTIONS_USE_ACK;
        See Also:
        SEND_OPTIONS_USE_ACK, send(Member[], Serializable , int), send(Member[], Serializable, int, ErrorHandler), Constant Field Values
    • Method Detail

      • addInterceptor

        void addInterceptor​(ChannelInterceptor interceptor)
        Adds an interceptor to the channel message chain.
        Parameters:
        interceptor - ChannelInterceptor
      • start

        void start​(int svc)
            throws ChannelException
        Starts up the channel. This can be called multiple times for individual services to start The svc parameter can be the logical or value of any constants
        Parameters:
        svc - int value of
        DEFAULT - will start all services
        MBR_RX_SEQ - starts the membership receiver
        MBR_TX_SEQ - starts the membership broadcaster
        SND_TX_SEQ - starts the replication transmitter
        SND_RX_SEQ - starts the replication receiver
        Note: In order for the membership broadcaster to transmit the correct information, it has to be started after the replication receiver.
        Throws:
        ChannelException - if a startup error occurs or the service is already started or an error occurs.
      • stop

        void stop​(int svc)
           throws ChannelException
        Shuts down the channel. This can be called multiple times for individual services to shutdown The svc parameter can be the logical or value of any constants
        Parameters:
        svc - int value of
        DEFAULT - will shutdown all services
        MBR_RX_SEQ - stops the membership receiver
        MBR_TX_SEQ - stops the membership broadcaster
        SND_TX_SEQ - stops the replication transmitter
        SND_RX_SEQ - stops the replication receiver
        Throws:
        ChannelException - if a startup error occurs or the service is already stopped or an error occurs.
      • send

        UniqueId send​(Member[] destination,
                      Serializable msg,
                      int options)
               throws ChannelException
        Send a message to one or more members in the cluster
        Parameters:
        destination - Member[] - the destinations, cannot be null or zero length, the reason for that is that a membership change can occur and at that time the application is uncertain what group the message actually got sent to.
        msg - Serializable - the message to send, has to be serializable, or a ByteMessage to send a pure byte array
        options - int - sender options, see class documentation for each interceptor that is configured in order to trigger interceptors
        Returns:
        a unique Id that identifies the message that is sent
        Throws:
        ChannelException - if a serialization error happens.
        See Also:
        ByteMessage, SEND_OPTIONS_USE_ACK, SEND_OPTIONS_ASYNCHRONOUS, SEND_OPTIONS_SYNCHRONIZED_ACK
      • send

        UniqueId send​(Member[] destination,
                      Serializable msg,
                      int options,
                      ErrorHandler handler)
               throws ChannelException
        Send a message to one or more members in the cluster
        Parameters:
        destination - Member[] - the destinations, null or zero length means all
        msg - ClusterMessage - the message to send
        options - int - sender options, see class documentation
        handler - ErrorHandler - handle errors through a callback, rather than throw it
        Returns:
        a unique Id that identifies the message that is sent
        Throws:
        ChannelException - - if a serialization error happens.
      • heartbeat

        void heartbeat()
        Sends a heart beat through the interceptor stacks Use this method to alert interceptors and other components to clean up garbage, timed out messages etc.
        If you application has a background thread, then you can save one thread, by configuring your channel to not use an internal heartbeat thread and invoking this method.
        See Also:
        setHeartbeat(boolean)
      • setHeartbeat

        void setHeartbeat​(boolean enable)
        Enables or disables internal heartbeat.
        Parameters:
        enable - boolean - default value is implementation specific
        See Also:
        heartbeat()
      • addMembershipListener

        void addMembershipListener​(MembershipListener listener)
        Add a membership listener, will get notified when a new member joins, leaves or crashes
        If the membership listener implements the Heartbeat interface the heartbeat() method will be invoked when the heartbeat runs on the channel
        Parameters:
        listener - MembershipListener
        See Also:
        MembershipListener
      • addChannelListener

        void addChannelListener​(ChannelListener listener)
        Add a channel listener, this is a callback object when messages are received
        If the channel listener implements the Heartbeat interface the heartbeat() method will be invoked when the heartbeat runs on the channel
        Parameters:
        listener - ChannelListener
        See Also:
        ChannelListener, Heartbeat
      • removeMembershipListener

        void removeMembershipListener​(MembershipListener listener)
        remove a membership listener, listeners are removed based on Object.hashCode and Object.equals
        Parameters:
        listener - MembershipListener
        See Also:
        MembershipListener
      • removeChannelListener

        void removeChannelListener​(ChannelListener listener)
        remove a channel listener, listeners are removed based on Object.hashCode and Object.equals
        Parameters:
        listener - ChannelListener
        See Also:
        ChannelListener
      • hasMembers

        boolean hasMembers()
        Returns true if there are any members in the group, this call is the same as getMembers().length > 0
        Returns:
        boolean - true if there are any members automatically discovered
      • getMembers

        Member[] getMembers()
        Get all current group members
        Returns:
        all members or empty array, never null
      • getLocalMember

        Member getLocalMember​(boolean incAlive)
        Return the member that represents this node. This is also the data that gets broadcasted through the membership broadcaster component
        Parameters:
        incAlive - - optimization, true if you want it to calculate alive time since the membership service started.
        Returns:
        Member
      • getMember

        Member getMember​(Member mbr)
        Returns the member from the membership service with complete and recent data. Some implementations might serialize and send membership information along with a message, and instead of sending complete membership details, only send the primary identifier for the member but not the payload or other information. When such message is received the application can retrieve the cached member through this call.
        In most cases, this is not necessary.
        Parameters:
        mbr - Member
        Returns:
        Member
      • getName

        String getName()
        Return the name of this channel.
        Returns:
        channel name
      • setName

        void setName​(String name)
        Set the name of this channel
        Parameters:
        name - The new channel name
      • getUtilityExecutor

        ScheduledExecutorService getUtilityExecutor()
        Return executor that can be used for utility tasks.
        Returns:
        the executor
      • setUtilityExecutor

        void setUtilityExecutor​(ScheduledExecutorService utilityExecutor)
        Set the executor that can be used for utility tasks.
        Parameters:
        utilityExecutor - the executor
      • getSendOptionValue

        static int getSendOptionValue​(String opt)
        Translates the name of an option to its integer value. Valid option names are "asynchronous" (alias "async"), "byte_message" (alias "byte"), "multicast", "secure", "synchronized_ack" (alias "sync"), "udp", "use_ack"
        Parameters:
        opt - The name of the option
        Returns:
        the int value of the passed option name
      • parseSendOptions

        static int parseSendOptions​(String input)
        Translates a comma separated list of option names to their bitwise-ORd value
        Parameters:
        input - A comma separated list of options, e.g. "async, multicast"
        Returns:
        a bitwise ORd value of the passed option names
      • getSendOptionsAsString

        static String getSendOptionsAsString​(int input)
        Translates an integer value of SendOptions to its human-friendly comma separated value list for use in JMX and such.
        Parameters:
        input - the int value of SendOptions
        Returns:
        the human-friendly string representation in a reverse order (i.e. the last option will be shown first)