one.world.util
Class Operation

java.lang.Object
  |
  +--one.world.util.AbstractHandler
        |
        +--one.world.util.Operation

All Implemented Interfaces:

EventHandler, Serializable

public final class Operation

extends AbstractHandler

Implementation of an operation. An operation manages a request/response interaction by setting a timeout and retrying if it does not receive a response within the timeout period.

An actual operation is started by invoking an operation on some event. The operation uses the request event handler for the actual event processing. It sends the eventual result to the continuation event handler. A single instance of this class can manage several concurrent request/response interactions.

To make sure that an operation sees the result of a request/response interaction, it overrides the source of the original event with the event handler returned by getResponseHandler().

Furthermore, to maintain its internal state, an operation replaces the event's closure with its own; it then restores the original closure before passing the response to the continuation. As a result, it is possible to use any object as the closure for a request managed by an operation, not just objects that are legal as values for a tuple field. However, closure replacement fails for ping-pong-like interactions, where both sides use operations. Applications that want to use operations for ping-pong-like interactions need to use chaining closures.

To use an operation with remote events, an application needs to first export the event handler returned by getResponseHandler() through REP and then set the source of all events embedded in a remote event to the corresponding symbolic handler.

For remote events, an operation replaces both the remote event's closure and the embedded event's closure with its own closure and restores them independently. Note that it does not unwrap the remote event carrying the response, but rather passes the entire remote event to the continuation.

Version:

$Revision: 1.16 $

See Also:

Tuple, one.world.rep, Serialized Form

Inner Class Summary

static class

Operation.ChainingClosure Implementation of a chaining closure.

Field Summary

EventHandler	continuation The event handler that processes the response.
EventHandler	request The event handler that processes the request.

Constructor Summary

Operation(int retries, long timeout, Timer timer, EventHandler request, EventHandler continuation)
Create a new operation.

Operation(Timer timer, EventHandler request, EventHandler continuation)
Create a new operation with the default number of retries and the default timeout.

Method Summary

protected void	finalize() Finalize this operation.
EventHandler	getResponseHandler() Get the response event handler for this operation.
protected boolean	handle1(Event e) Handle the specified event.

Methods inherited from class one.world.util.AbstractHandler

handle, isNotValid, respond, respond, respond, respond, respond, respond

Methods inherited from class java.lang.Object

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

Field Detail

request

public EventHandler request

The event handler that processes the request.

continuation

public EventHandler continuation

The event handler that processes the response.

Constructor Detail

Operation

public Operation(Timer timer,
                 EventHandler request,
                 EventHandler continuation)

Create a new operation with the default number of retries and the default timeout. Note that the request and continuation event handlers may be null.

Parameters:

timer - The timer.

request - The request event handler.

continuation - The continuation event handler.

Throws:

NullPointerException - Signals that timer is null.

See Also:

Constants.OPERATION_RETRIES, Constants.OPERATION_TIMEOUT

Operation

public Operation(int retries,
                 long timeout,
                 Timer timer,
                 EventHandler request,
                 EventHandler continuation)

Create a new operation. Note that the request and continuation event handlers may be null.

Parameters:

retries - The number of retries.

timeout - The timeout.

timer - The timer.

request - The request event handler.

continuation - The continuation event handler.

Throws:

NullPointerException - Signals that timer is null.

IllegalArgumentException - Signals that retries is negative or that timeout is non-positive.

Method Detail

finalize

protected void finalize()

Finalize this operation.

Overrides:

finalize in class Object

getResponseHandler

public EventHandler getResponseHandler()

Get the response event handler for this operation.

Returns:

The response event handler for this operation.

handle1

protected boolean handle1(Event e)

Handle the specified event.

Note that the specified event must be a valid event with the exception of the source, which is overridden by this method. Furthermore, for remote events, the embedded event must have as its source a symbolic handler obtained by exporting the event handler returned by getResponseHandler().

Overrides:

handle1 in class AbstractHandler

Following copied from class: one.world.util.AbstractHandler

Parameters:

e - The event to handle.

Returns:

true if the specified event was handled by this method.