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:
    OortMasterService

    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.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected org.slf4j.Logger logger  
      • Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

        FAILED, RUNNING, STARTED, STARTING, STOPPED, STOPPING
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected OortService​(Oort oort, java.lang.String name)
      Creates an OortService with the given name.
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected void doStart()  
      protected void doStop()  
      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.
      LocalSession getLocalSession()  
      java.lang.String getName()  
      Oort getOort()  
      long getTimeout()  
      protected abstract OortService.Result<R> onForward​(OortService.Request request)
      Subclasses must implement this method, that runs on the owner node, to implement the action functionality.
      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.
      protected void onForwardMessage​(java.util.Map<java.lang.String,java.lang.Object> data, boolean broadcast)  
      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.
      boolean onMessage​(ServerSession from, ServerChannel channel, ServerMessage.Mutable message)
      Callback invoked when a message is being published.
      protected void onResultMessage​(java.util.Map<java.lang.String,java.lang.Object> data)  
      void setTimeout​(long timeout)  
      java.lang.String toString()  
      • Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

        addLifeCycleListener, getState, getState, getStopTimeout, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, setStopTimeout, start, stop
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • logger

        protected final org.slf4j.Logger logger
    • 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
      • onMessage

        public boolean onMessage​(ServerSession from,
                                 ServerChannel channel,
                                 ServerMessage.Mutable message)
        Description copied from interface: ServerChannel.MessageListener

        Callback invoked when a message is being published.

        Implementers can decide to return false to signal that the message should not be published.

        Specified by:
        onMessage in interface ServerChannel.MessageListener
        Parameters:
        from - the session that publishes the message
        channel - the channel the message is published to
        message - the message to be published
        Returns:
        whether the message should be published or not
      • 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 java.lang.Object