Package com.yahoo.messagebus

Class Routable

  • Direct Known Subclasses:
    Message, Reply
    public abstract class Routable
extends java.lang.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 Summary

      Constructors 
      Constructor Description
      Routable()  

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void discard()
      Discards this routable.
      CallStack getCallStack()
      Returns the callstack of this routable.
      java.lang.Object getContext()
      Returns the context of this routable.
      abstract com.yahoo.text.Utf8String getProtocol()
      Return the name of the protocol that defines this routable.
      Trace getTrace()
      Returns the trace object of this routable.
      abstract int getType()
      Returns the type of this routable.
      ReplyHandler popHandler()
      This is a convenience method for calling CallStack.pop(Routable) on the CallStack of this Routable.
      void pushHandler​(ReplyHandler handler)
      Pushes the given reply handler onto the call stack of this routable, also storing the current context.
      void setContext​(java.lang.Object context)
      Sets a new context for this routable.
      void swapState​(Routable rhs)
      Swaps the state that makes this routable unique to another routable.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Routable

        public Routable()

    • Method Detail

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

      • getContext

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

      • setContext

        public void setContext​(java.lang.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.