Package com.yahoo.messagebus

Class Routable

java.lang.Object
com.yahoo.messagebus.Routable
Direct Known Subclasses:
Message, Reply
public abstract class Routable extends Object
Superclass for objects that can be either explicitly (Message) or implicitly (Reply) routed. Note that protocol implementors should never subclass this directly, but rather through the Message and Reply classes. A routable can be regarded as a protocol-defined value with additional message bus related state. The state is what differentiates two Routables that carry the same value. This includes the application context attached to the routable and the CallStack used to track the path of the routable within messagebus. When a routable is copied (if the protocol supports it) only the value part is copied. The state must be explicitly transfered by invoking the swapState(Routable) method. That method is used to transfer the state from a message to the corresponding reply, or to a different message if the application decides to replace it.
Author:
Simon Thoresen Hult

  • Constructor Details

    • Routable

      public Routable()

  • Method Details

    • discard

      public void discard()
      Discards this routable. Invoking this prevents the auto-generation of replies if you later discard the routable. This is a required step to ensure safe shutdown if you need destroy a message bus instance while there are still messages and replies alive in your application.

    • swapState

      public void swapState(Routable rhs)
      Swaps the state that makes this routable unique to another routable. The state is what identifies a routable for message bus, so only one message can ever have the same state. This function must be called explicitly when cloning and copying messages.
      Parameters:
      rhs - The routable to swap state with.

    • pushHandler

      public void pushHandler(ReplyHandler handler)
      Pushes the given reply handler onto the call stack of this routable, also storing the current context.
      Parameters:
      handler - The handler to push.

    • popHandler

      public ReplyHandler popHandler()

      This is a convenience method for calling CallStack.pop(Routable) on the CallStack of this Routable. It equals calling routable.getCallStack().pop(routable).

      Returns:
      The handler that was popped.
      See Also:

    • getContext

      public Object getContext()
      Returns the context of this routable.

    • setContext

      public void setContext(Object context)
      Sets a new context for this routable. Please note that the context is not something that is passed along a message, it is simply a user context for the handler currently manipulating a message. When the corresponding reply reaches the registered reply handler, its content will be the same as that of the outgoing message. More technically, this context is contained in the callstack of a routable.

    • getCallStack

      public CallStack getCallStack()
      Returns the callstack of this routable.

    • getTrace

      public Trace getTrace()
      Returns the trace object of this routable.

    • getProtocol

      public abstract com.yahoo.text.Utf8String getProtocol()
      Return the name of the protocol that defines this routable. This must be implemented by all inheriting classes, and should then return the result of Protocol.getName() of its protocol.
      Returns:
      the name of the protocol defining this message.

    • getType

      public abstract int getType()
      Returns the type of this routable. The id '0' is reserved for the EmptyReply class. Other ids must be defined by the application protocol.