Package com.yahoo.messagebus

Class MessageBus

java.lang.Object
com.yahoo.messagebus.MessageBus
All Implemented Interfaces:
ConfigHandler, MessageHandler, NetworkOwner, ReplyHandler
public class MessageBus extends 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 Details

    • MessageBus

      public MessageBus(Network net, List<Protocol> protocols)

      Convenience constructor that proxies MessageBus(Network, MessageBusParams) by adding the given protocols to a default MessageBusParams object.

      Parameters:
      net - The network to associate with.
      protocols - An array of protocols to register.

    • 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, and this bus will be the single owner of this net.

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

    • MessageBus

      public MessageBus(NetworkMultiplexer net, MessageBusParams params)

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

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

  • Method Details

    • register

      public void register(MessageBus.SendBlockedMessages sender)

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

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

      Parameters:
      handler - The reply handler to receive the replies for the session.
      Returns:
      The created session.

    • createSourceSession

      public SourceSession createSourceSession(ReplyHandler handler, SourceSessionParams params)

      This is a convenience method to call createSourceSession(SourceSessionParams) by first assigning the reply handler to the parameter object.

      Parameters:
      handler - The reply handler to receive the replies for the session.
      params - The parameters to control the session.
      Returns:
      The created session.

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

    • createDetachedIntermediateSession

      public IntermediateSession createDetachedIntermediateSession(IntermediateSessionParams params)

    • createDestinationSession

      public DestinationSession createDestinationSession(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.

    • createDetachedDestinationSession

      public DestinationSession createDetachedDestinationSession(DestinationSessionParams params)

    • connect

      public void connect(String session, boolean broadcast)
      Connects the given session to the network, so it will receive requests.

    • unregisterSession

      public void unregisterSession(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, 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.

    • deliverReply

      public void deliverReply(Reply reply, ReplyHandler handler)

    • 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

      @Deprecated public Resender getResender()
      Deprecated.

      Returns the resender that is running within this message bus.

      Returns:
      The resender.

    • getPendingCount

      @Deprecated public int getPendingCount()
      Deprecated.

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

      Returns:
      The pending count.

    • getPendingSize

      @Deprecated public int getPendingSize()
      Deprecated.

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

      Returns:
      The pending size.

    • setMaxPendingCount

      @Deprecated public void setMaxPendingCount(int maxCount)
      Deprecated.

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

      Parameters:
      maxCount - The max count.

    • getMaxPendingCount

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

    • setMaxPendingSize

      @Deprecated public void setMaxPendingSize(int maxSize)
      Deprecated.

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

      Parameters:
      maxSize - The max size.

    • getMaxPendingSize

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

    • getRoutingTable

      public RoutingTable getRoutingTable(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(String protocolName, String policyName, 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, String policyName, 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 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.