Package com.yahoo.messagebus

Class MessageBus

  • All Implemented Interfaces:
    ConfigHandler, MessageHandler, NetworkOwner, ReplyHandler
    public class MessageBus
extends java.lang.Object
implements ConfigHandler, NetworkOwner, MessageHandler, ReplyHandler

    A message bus contains the factory for creating sessions to send, receive and forward messages.

    There are three types of sessions:

    • Source sessions sends messages and receives replies
    • Intermediate sessions receives messages on their way to their final destination, and may decide to forward the messages or reply directly.
    • Destination sessions are the final recipient of messages, and are expected to reply to every one of them, but may not forward messages.

    A message bus is configured with a protocol. This table enumerates the permissible routes from intermediates to destinations and the messaging semantics of each hop.

    The responsibilities of a message bus are:
    • Assign a route to every send message from its routing table
    • Deliver every message it accepts to the next hop on its route or deliver a failure reply.
    • Deliver replies back to message sources through all the intermediate hops.
    A runtime will typically
    • Create a message bus implementation and set properties on this implementation once.
    • Create sessions using that message bus many places.
    Author:
    bratseth, Simon Thoresen Hult

    • Constructor Detail

      • MessageBus

        public MessageBus​(Network net,
                  MessageBusParams params)

        Constructs an instance of message bus. This requires a network object that it will associate with. This assignment may not change during the lifetime of this message bus.

        Parameters:
        net - The network to associate with.
        params - The parameters that controls this bus.

    • Method Detail

      • destroy

        public boolean destroy()

        Sets the destroyed flag to true. The very first time this method is called, it cleans up all its dependencies. Even if you retain a reference to this object, all of its content is allowed to be garbage collected.

        Returns:
        True if content existed and was destroyed.

      • sync

        public void sync()

        Synchronize with internal threads. This method will handshake with all internal threads. This has the implicit effect of waiting for all active callbacks. Note that this method should never be invoked from a callback since that would make the thread wait for itself... forever. This method is typically used to untangle during session shutdown.

      • createSourceSession

        public SourceSession createSourceSession​(SourceSessionParams params)

        Creates a source session on top of this message bus.

        Parameters:
        params - The parameters to control the session.
        Returns:
        The created session.

      • createIntermediateSession

        public IntermediateSession createIntermediateSession​(java.lang.String name,
                                                     boolean broadcastName,
                                                     MessageHandler msgHandler,
                                                     ReplyHandler replyHandler)

        This is a convenience method to call createIntermediateSession(IntermediateSessionParams) with default values for the IntermediateSessionParams object.

        Parameters:
        name - The local unique name for the created session.
        broadcastName - Whether or not to broadcast this session's name on the network.
        msgHandler - The handler to receive the messages for the session.
        replyHandler - The handler to received the replies for the session.
        Returns:
        The created session.

      • createIntermediateSession

        public IntermediateSession createIntermediateSession​(IntermediateSessionParams params)

        Creates an intermediate session on top of this message bus using the given handlers and parameter object.

        Parameters:
        params - The parameters to control the session.
        Returns:
        The created session.

      • createDestinationSession

        public DestinationSession createDestinationSession​(java.lang.String name,
                                                   boolean broadcastName,
                                                   MessageHandler handler)

        This is a convenience method to call createDestinationSession(DestinationSessionParams) with default values for the DestinationSessionParams object.

        Parameters:
        name - The local unique name for the created session.
        broadcastName - Whether or not to broadcast this session's name on the network.
        handler - The handler to receive the messages for the session.
        Returns:
        The created session.

      • createDestinationSession

        public DestinationSession createDestinationSession​(DestinationSessionParams params)

        Creates a destination session on top of this message bus using the given handlers and parameter object.

        Parameters:
        params - The parameters to control the session.
        Returns:
        The created session.

      • unregisterSession

        public void unregisterSession​(java.lang.String name,
                              boolean broadcastName)

        This method is invoked by the IntermediateSession.destroy() to unregister sessions from receiving data from message bus.

        Parameters:
        name - The name of the session to remove.
        broadcastName - Whether or not session name was broadcast.

      • handleMessage

        public void handleMessage​(Message msg)
        Description copied from interface: MessageHandler
        This function is called when a message arrives.
        Specified by:
        handleMessage in interface MessageHandler
        Parameters:
        msg - The message that arrived.

      • handleReply

        public void handleReply​(Reply reply)
        Description copied from interface: ReplyHandler
        This function is called when a reply arrives.
        Specified by:
        handleReply in interface ReplyHandler
        Parameters:
        reply - The reply that arrived.

      • deliverMessage

        public void deliverMessage​(Message msg,
                           java.lang.String session)
        Description copied from interface: NetworkOwner
        All messages that arrive in the network layer is passed to its owner through this function.
        Specified by:
        deliverMessage in interface NetworkOwner
        Parameters:
        msg - The message that just arrived from the network.
        session - The name of the session that is the recipient of the request.

      • putProtocol

        public void putProtocol​(Protocol protocol)

        Adds a protocol to the internal repository of protocols, replacing any previous instance of the protocol and clearing the associated routing policy cache.

        Parameters:
        protocol - The protocol to add.

      • getProtocol

        public Protocol getProtocol​(com.yahoo.text.Utf8Array name)
        Description copied from interface: NetworkOwner
        All messages are sent across the network with its accompanying protocol name so that it can be decoded at the receiving end. The network queries its owner through this function to resolve the protocol from its name.
        Specified by:
        getProtocol in interface NetworkOwner
        Parameters:
        name - The name of the protocol to return.
        Returns:
        The named protocol.

      • getProtocol

        public Protocol getProtocol​(com.yahoo.text.Utf8String name)

      • deliverReply

        public void deliverReply​(Reply reply,
                         ReplyHandler handler)
        Description copied from interface: NetworkOwner
        All replies that arrive in the network layer is passed through this to unentangle it from the network thread.
        Specified by:
        deliverReply in interface NetworkOwner
        Parameters:
        reply - The reply that just arrived from the network.
        handler - The handler that is to receive the reply.

      • setupRouting

        public void setupRouting​(RoutingSpec spec)
        Description copied from interface: ConfigHandler
        Sets the routing specification for this client. This will be done synchronously during initialization, and then subsequently whenever an updated configuration is available.
        Specified by:
        setupRouting in interface ConfigHandler
        Parameters:
        spec - The routing specification.

      • getResender

        public Resender getResender()

        Returns the resender that is running within this message bus.

        Returns:
        The resender.

      • getPendingCount

        public int getPendingCount()

        Returns the number of messages received that have not been replied to yet.

        Returns:
        The pending count.

      • getPendingSize

        public int getPendingSize()

        Returns the size of messages received that have not been replied to yet.

        Returns:
        The pending size.

      • setMaxPendingCount

        public void setMaxPendingCount​(int maxCount)

        Sets the maximum number of messages that can be received without being replied to yet.

        Parameters:
        maxCount - The max count.

      • getMaxPendingCount

        public int getMaxPendingCount()
        Gets maximum number of messages that can be received without being replied to yet.

      • setMaxPendingSize

        public void setMaxPendingSize​(int maxSize)

        Sets the maximum size of messages that can be received without being replied to yet.

        Parameters:
        maxSize - The max size.

      • getMaxPendingSize

        public int getMaxPendingSize()
        Gets maximum combined size of messages that can be received without being replied to yet.

      • getRoutingTable

        public RoutingTable getRoutingTable​(java.lang.String name)

        Returns a named routing table, may return null.

        Parameters:
        name - The name of the routing table to return.
        Returns:
        The routing table object.

      • getRoutingTable

        public RoutingTable getRoutingTable​(com.yahoo.text.Utf8String name)

        Returns a named routing table, may return null.

        Parameters:
        name - The name of the routing table to return.
        Returns:
        The routing table object.

      • getRoutingPolicy

        public RoutingPolicy getRoutingPolicy​(java.lang.String protocolName,
                                      java.lang.String policyName,
                                      java.lang.String policyParam)

        Returns a routing policy that corresponds to the argument protocol name, policy name and policy parameter. This will cache reuse all policies as soon as they are first requested.

        Parameters:
        protocolName - The name of the protocol to invoke Protocol.createPolicy(String,String) on.
        policyName - The name of the routing policy to retrieve.
        policyParam - The parameter for the routing policy to retrieve.
        Returns:
        A corresponding routing policy, or null.

      • getRoutingPolicy

        public RoutingPolicy getRoutingPolicy​(com.yahoo.text.Utf8String protocolName,
                                      java.lang.String policyName,
                                      java.lang.String policyParam)

        Returns a routing policy that corresponds to the argument protocol name, policy name and policy parameter. This will cache reuse all policies as soon as they are first requested.

        Parameters:
        protocolName - The name of the protocol to invoke Protocol.createPolicy(String,String) on.
        policyName - The name of the routing policy to retrieve.
        policyParam - The parameter for the routing policy to retrieve.
        Returns:
        A corresponding routing policy, or null.

      • getConnectionSpec

        public java.lang.String getConnectionSpec()

        Returns the connection spec string for the network layer of this message bus. This is merely a proxy of the same function in the network layer.

        Returns:
        The connection string.