org.lightwolf
Class Continuation

java.lang.Object
  org.lightwolf.Continuation

All Implemented Interfaces:

Cloneable

public class Continuation
extends Object
implements Cloneable

An object that stores a flow's execution context for further resuming. Usage requires invocation of checkpoint() and resume() on an instance of this class. It is allowed to subclass this class as a way to associate additional data or functionality to a continuation.

Author:

Fernando Colombo

Constructor Summary

Continuation()
Creates a new continuation.

Method Summary

Future<?>	activate()
Future<?>	activate(Object result)
boolean	checkpoint() Places a checkpoint on the current flow, which can be used resume execution from the point of invocation.
Continuation	clone() Returns an identical, independent copy of this continuation.
void	placeOnCheckpoint(Flow flow)
void	placeOnCheckpointAndForget(Flow flow)
Object	resume() Creates a new flow and resumes it from the last checkpoint.
Object	resume(Flow flow) Resumes the informed flow from the last checkpoint.
Object	resumeAndForget() Creates a new flow and resumes it from the last checkpoint, throwing away the checkpoint.
Object	resumeAndForget(Flow flow) Resumes the informed flow from the last checkpoint, throwing away the checkpoint.

Methods inherited from class java.lang.Object

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

Constructor Detail

Continuation

public Continuation()

Creates a new continuation. This constructor doesn't set any checkpoint. Use checkpoint() for that.

See Also:

checkpoint()

Method Detail

clone

public Continuation clone()
                   throws CloneNotSupportedException

Returns an identical, independent copy of this continuation. If this continuation contains a checkpoint, the returned object will have a copy of such checkpoint.

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

checkpoint

public final boolean checkpoint()

Places a checkpoint on the current flow, which can be used resume execution from the point of invocation. The checkpoint contains the values of parameters, local variables, temporary data and instruction pointers, of all frames from the flow-creator (inclusive) to the point of invocation.

After invocation, it's possible to call resume() on this continuation, so a flow can resume from the checkpoint. When a checkpoint is created, this method returns true. Upon resuming, this method returns false. The following example illustrates this behavior:

    void example() {
        System.out.println("Before doFlow()");
        Continuation continuation = doFlow();
        System.out.println("After doFlow()");
        continuation.resume();
        System.out.println("After continuation.resume()");
    }
 
    @FlowMethod
    FlowContext doFlow() {
        System.out.println("Before doCheckpoint()");
        Continuation continuation = doCheckpoint();
        System.out.println("After doCheckpoint()");
        return continuation;
    }
 
    @FlowMethod
    Continuation doCheckpoint() {
        Continuation continuation = new Continuation();
        System.out.println("Before continuation.checkpoint()");
        if (continuation.checkpoint()) {
            System.out.println("Checkpoint is set.");
        } else {
            System.out.println("We are resuming.");
        }
        return continuation;
    }
 

The above example prints the following:

     Before doFlow()
     Before doCheckpoint()
     Before continuation.checkpoint()
     Checkpoint is set.
     After doCheckpoint()
     After doFlow()
     We are resuming.
     After doCheckpoint()
     After continuation.resume()
 

This method may return multiple times, at the discretion of whoever is using the continuation. Each time it might return in a different flow. But it's guaranteed that whenever this method returns true, it will return in the same flow as the invoker.

A continuation can hold at most one checkpoint, so this method throws away any previous checkpoint that this continuation was holding.

Returns:

true if a checkpoint was created, false if this method is resuming from a previously created checkpoint.

Throws:

IllegalStateException - If the invoker is not a FlowMethod.

resume

public Object resume()

Creates a new flow and resumes it from the last checkpoint. Execution resumes from the last invocation of checkpoint() on this continuation. Such invocation returns false, indicating that execution is being resumed.

The new flow will execute synchronously. This method returns only then the flow-creator returns, as if by invocation of Flow.resume(). If the resumed flow sends a signal, this method throws the corresponding FlowSignal. In other words, the invoker will be the flow-controller.

This method behaves exactly as:

     Flow flow = Flow.newFlow();
     continuation.resume(flow);
 

Before resuming, this method performs a copy of the current checkpoint, so a future resume operation will succeed. If there is no intention to resume again, one should call resumeAndForget().

Returns:

The flow-creator's result.

Throws:

IllegalStateException - If there is no stored checkpoint on this continuation.

See Also:

resume(Flow), resumeAndForget(), resumeAndForget(Flow)

resume

public Object resume(Flow flow)

Resumes the informed flow from the last checkpoint. This method is similar to resume(). The difference is that no new flow is created. Instead, the informed flow is resumed.

Returns:

The flow-creator's result.

Throws:

IllegalStateException - If there is no stored checkpoint on this continuation, or if the informed flow is on an invalid state for resuming.

NullPointerException - If the informed flow is null.

See Also:

resume(), resumeAndForget(Flow)

resumeAndForget

public Object resumeAndForget()

Creates a new flow and resumes it from the last checkpoint, throwing away the checkpoint. This method is similar to resume(). The difference is that after invocation, this continuation will have no checkpoint(), which means that further invocations of resume methods will throw an exception.

This method is cheaper than resume(), because it does not involves a copy of the current checkpoint.

Returns:

The flow-creator's result.

Throws:

IllegalStateException - If there is no stored checkpoint on this continuation.

See Also:

resume(), resumeAndForget(Flow)

resumeAndForget

public Object resumeAndForget(Flow flow)

Resumes the informed flow from the last checkpoint, throwing away the checkpoint. This method is similar to resume(Flow). The difference is that after invocation, this continuation will have no checkpoint(), which means that further invocations of resume methods will throw an exception.

This method is cheaper than resume(Flow), because it does not involves a copy of the current checkpoint.

Returns:

The flow-creator's result.

Throws:

IllegalStateException - If there is no stored checkpoint on this continuation, or if the informed flow is on an invalid state for resuming.

NullPointerException - If the informed flow is null.

See Also:

resume(), resumeAndForget()

activate

public Future<?> activate()

activate

public Future<?> activate(Object result)

placeOnCheckpoint

public void placeOnCheckpoint(Flow flow)

placeOnCheckpointAndForget

public void placeOnCheckpointAndForget(Flow flow)