Package org.cometd.oort

Class OortService<R,​C>

  • Type Parameters:
    R - the result type
    C - the opaque context type
    All Implemented Interfaces:
    java.util.EventListener, Bayeux.BayeuxListener, ConfigurableServerChannel.ServerChannelListener, ServerChannel.MessageListener, org.eclipse.jetty.util.component.LifeCycle
    Direct Known Subclasses:
    OortPrimaryService
    public abstract class OortService<R,​C>
extends org.eclipse.jetty.util.component.AbstractLifeCycle
implements ServerChannel.MessageListener

    An OortService allows applications to forward actions to Oort nodes that own the entity onto which the action should be applied.

    An OortService builds on the concept introduced by OortObject that the ownership of a particular entity belongs only to one node. Any node can read the entity, but only the owner can create/modify/delete it.

    In order to perform actions that modify the entity, a node has to know what is the node that owns the entity, and then forward the action to the owner node.

    OortService provides the facilities to forward the action to the owner node and return the result of the action, or its failure.

    OortServices are usually created at application startup, but may be created and destroyed on-the-fly. In both cases, they must be started to make them functional and stopped when they are no longer needed.

    Usage of OortService follows these steps:

    1. The application running in the requesting node identifies the owner node and calls forward(String, Object, Object), passing the Oort URL of the owner node, the action data, and an opaque context
    2. The application implements onForward(Request), which is executed in the owner node. In this method the action data is used to perform the action that modifies the entity, and the result is returned (or an exception thrown in case of failure).
    3. The application implements onForwardSucceeded(Object, Object) (which is executed in the requesting node) which provides as parameters the result of the action from the second step and the opaque context from the first step.
    4. The application implements onForwardFailed(Object, Object) (which is executed in the requesting node) which provides as parameters the failure from the second step and the opaque context from the first step. The failure object is the message string of a generic exception, or the failure returned by OortService.Result.failure(Object).

    The steps above do not change if the requesting node and the owner node are the same.

    • Constructor Detail

      • OortService

        protected OortService​(Oort oort,
                      java.lang.String name)
        Creates an OortService with the given name.
        Parameters:
        oort - the Oort where this service lives
        name - the unique name across the cluster of this service

    • Method Detail

      • getOort

        public Oort getOort()
        Returns:
        the Oort of this service

      • getName

        public java.lang.String getName()
        Returns:
        the name of this service

      • getLocalSession

        public LocalSession getLocalSession()
        Returns:
        the local session associated with this service

      • getTimeout

        public long getTimeout()
        Returns:
        the timeout, in milliseconds, for an action to return a result (by default 5000 ms)

      • setTimeout

        public void setTimeout​(long timeout)
        Parameters:
        timeout - the timeout, in milliseconds, for an action to return a result

      • doStart

        protected void doStart()
                throws java.lang.Exception
        Overrides:
        doStart in class org.eclipse.jetty.util.component.AbstractLifeCycle
        Throws:
        java.lang.Exception

      • doStop

        protected void doStop()
               throws java.lang.Exception
        Overrides:
        doStop in class org.eclipse.jetty.util.component.AbstractLifeCycle
        Throws:
        java.lang.Exception

      • forward

        protected boolean forward​(java.lang.String targetOortURL,
                          java.lang.Object parameter,
                          C context)

        Subclasses must call this method to forward the action to the owner node.

        If the targetOortURL is null, then the action is broadcast to all nodes. Nodes that receive an action request that they can't fullfill because they don't own the entity the action should be applied to must return OortService.Result.ignore(Object).

        Parameters:
        targetOortURL - the owner node Oort URL, or null to broadcast the action to all nodes
        parameter - the action parameter that will be passed to onForward(Request)
        context - the opaque context passed to onForwardSucceeded(Object, Object)
        Returns:
        whether the forward succeeded

      • onForwardMessage

        protected void onForwardMessage​(java.util.Map<java.lang.String,​java.lang.Object> data,
                                boolean broadcast)

      • onResultMessage

        protected void onResultMessage​(java.util.Map<java.lang.String,​java.lang.Object> data)

      • onForwardSucceeded

        protected abstract void onForwardSucceeded​(R result,
                                           C context)
        Subclasses must implement this method, that runs on the requesting node, to complete the functionality after the action has been successfully run on the owner node.
        Parameters:
        result - the result of the action
        context - the opaque context from forward(String, Object, Object)

      • onForwardFailed

        protected abstract void onForwardFailed​(java.lang.Object failure,
                                        C context)
        Subclasses must implement this method, that runs on the requesting node, to complete the functionality after the action failed on the owner node.
        Parameters:
        failure - the failure of the action
        context - the opaque context from forward(String, Object, Object)

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class org.eclipse.jetty.util.component.AbstractLifeCycle