Interface Channel

All Known Subinterfaces:
ManagedChannel
All Known Implementing Classes:
GroupChannel
public interface Channel
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:

  • send messages
  • receive message (by registering a ChannelListener
  • get all members of the group getMembers()
  • receive notifications of members added and members disappeared by registering a MembershipListener
The channel has 5 major components:
  • Data receiver, with a built-in thread pool to receive messages from other peers
  • Data sender, an implementation for sending data using NIO or java.io
  • Membership listener,listens for membership broadcasts
  • Membership broadcaster, broadcasts membership pings.
  • 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]
See Also:

  • Field Details

  • Method Details

    • addInterceptor

      void addInterceptor(ChannelInterceptor interceptor)
      Adds an interceptor to the stack for message processing. Interceptors are ordered in the way they are added. 
      
channel.addInterceptor(A);
channel.addInterceptor(C);
channel.addInterceptor(B);
      Will result in an interceptor stack like this: A -> C -> B

      The complete stack will look like this: Channel -> A -> C -> B -> ChannelCoordinator

      Parameters:
      interceptor - ChannelInterceptorBase

    • 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 - one 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 shut down. The svc parameter can be the logical or value of any constants
      Parameters:
      svc - one of:
      • DEFAULT - will shut down 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 shutdown 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. Note that a membership change can occur between obtaining the member list and sending the message, so 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 the msg is null, if the destination is null or is empty, or if a serialization error happens.
      See Also:

    • 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. Note that a membership change can occur between obtaining the member list and sending the message, so the application is uncertain what group the message actually got sent to.
      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 the msg is null, if the destination is null or is empty, or 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 your 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

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

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

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

    • removeMembershipListener

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

    • removeChannelListener

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

    • 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 broadcast 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 comma-separated string representation of the set options