org.cometd.oort

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	OortService.Request Encapsulates a forwarded request.
static class	OortService.Result<U> Encapsulates the result of a forwarded request returned by onForward(Request).
static class	OortService.ServerContext Utility context that stores the ServerSession and the ServerMessage.

Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

org.eclipse.jetty.util.component.AbstractLifeCycle.AbstractLifeCycleListener

Nested classes/interfaces inherited from interface org.cometd.bayeux.server.ConfigurableServerChannel.ServerChannelListener

ConfigurableServerChannel.ServerChannelListener.Weak

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

org.eclipse.jetty.util.component.LifeCycle.Listener

Field Summary

Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

FAILED, RUNNING, STARTED, STARTING, STOPPED, STOPPING

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	OortService(Oort oort, String name) Creates an OortService with the given name.

Method Summary

Modifier and Type	Method and Description
protected void	doStart()
protected void	doStop()
protected boolean	forward(String targetOortURL, Object parameter, C context) Subclasses must call this method to forward the action to the owner node.
LocalSession	getLocalSession()
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(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(Map<String,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) Blocking version of ServerChannel.MessageListener.onMessage(ServerSession, ServerChannel, ServerMessage.Mutable, Promise).
protected void	onResultMessage(Map<String,Object> data)
void	setTimeout(long timeout)
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

Methods inherited from interface org.cometd.bayeux.server.ServerChannel.MessageListener

onMessage

Methods inherited from interface org.eclipse.jetty.util.component.LifeCycle

start, stop

Constructor Detail

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 Detail

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