Class OortService<R,C>

java.lang.Object
org.eclipse.jetty.util.component.AbstractLifeCycle
org.cometd.oort.OortService<R,C>
Type Parameters:
R - the result type
C - the opaque context type
All Implemented Interfaces:
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 Details

    • OortService

      protected OortService(Oort oort, 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 Details

    • getOort

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

    • getName

      public 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 Exception
      Overrides:
      doStart in class org.eclipse.jetty.util.component.AbstractLifeCycle
      Throws:
      Exception

    • doStop

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

    • forward

      protected boolean forward(String targetOortURL, 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

      Blocking version of ServerChannel.MessageListener.onMessage(ServerSession, ServerChannel, ServerMessage.Mutable, Promise).

      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 processing should continue

    • onForwardMessage

      protected void onForwardMessage(Map<String,Object> data, boolean broadcast)

    • onResultMessage

      protected void onResultMessage(Map<String,Object> data)

    • onForward

      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.

      The result to return is OortService.Result.success(Object) or OortService.Result.failure(Object) if the implementation of this method was able to find the entity on which the action functionality was meant to be applied, or OortService.Result.ignore(Object) if the entity was not found.

      Parameters:
      request - the request containing the parameter passed from forward(String, Object, Object)
      Returns:
      the result containing the data that will be passed to onForwardSucceeded(Object, Object)

    • 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(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 String toString()
      Overrides:
      toString in class org.eclipse.jetty.util.component.AbstractLifeCycle