de.esoco.coroutine

Class CoroutineStep<I,O>

java.lang.Object

org.obrel.core.RelatedObject

de.esoco.coroutine.CoroutineStep<I,O>

All Implemented Interfaces:

de.esoco.lib.property.Fluent<CoroutineStep<I,O>>, org.obrel.core.FluentRelatable<CoroutineStep<I,O>>, org.obrel.core.Relatable

Direct Known Subclasses:

AsynchronousChannelStep, CallSubroutine, ChannelStep, CodeExecution, Collect, Condition, Delay, Iteration, Loop, Select

public abstract class CoroutineStep<I,O>
extends org.obrel.core.RelatedObject
implements org.obrel.core.FluentRelatable<CoroutineStep<I,O>>

This is the base class for all steps of coroutines. For simple steps it is sufficient to implement the single abstract method execute(Object, Continuation) which must perform the actual (blocking) code execution. The default implementations of runBlocking(Object, Continuation) and runAsync(CompletableFuture, CoroutineStep, Continuation) then invoke this method as needed.

In most cases it is not necessary to extend this class because the 'step' sub-package already contains implementations of several common steps. For example, a simple code execution can be achieved by wrapping a closure in an instance of the CodeExecution step.

Creating a new step subclass is only needed to implement advanced coroutine suspensions that are not already provided by existing steps. In such a case it is typically also necessary to override the method runAsync(CompletableFuture, CoroutineStep, Continuation) to check for the suspension condition. If a suspension is necessary a Suspension object can be created by invoking Continuation.suspend(CoroutineStep, CoroutineStep) for the current step. The suspension object can then be used by code that waits for some external condition to resume the coroutine when appropriate.

It is recommended that a step implementation provides one or more static factory methods alongside the constructor(s). These factory methods can then be used as static imports for the fluent builder API of coroutines.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	CoroutineStep() Creates a new instance.

Method Summary

Modifier and Type	Method and Description
protected abstract O	execute(I rInput, Continuation<?> rContinuation) This method must be implemented by subclasses to provide the actual functionality of this step.
protected O	fail(java.lang.Throwable eError, Continuation<?> rContinuation) Signals an execution failure to the given continuation.
void	runAsync(java.util.concurrent.CompletableFuture<I> fPreviousExecution, CoroutineStep<O,?> rNextStep, Continuation<?> rContinuation) Runs this execution step asynchronously as a continuation of a previous code execution in a CompletableFuture and proceeds to the next step afterwards.
O	runBlocking(I rInput, Continuation<?> rContinuation) Runs this execution immediately, blocking the current thread until the execution finishes.
protected void	terminateCoroutine(Continuation<?> rContinuation) Allow subclasses to terminate the coroutine they currently run in.
java.lang.String	toString()

Methods inherited from class org.obrel.core.RelatedObject

deleteRelation, get, getRelation, getRelations, notifyRelationListeners, readRelations, relationsEqual, relationsHashCode, relationsString, set, set, transform, writeRelations

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.obrel.core.FluentRelatable

with, with, with

Methods inherited from interface org.obrel.core.Relatable

deleteRelation, deleteRelation, deleteRelations, get, get, get, getAll, getRelation, getRelationCount, getRelations, getRelations, hasFlag, hasRelation, hasRelations, init, set, set, set, set, set, streamRelations, transform

Methods inherited from interface de.esoco.lib.property.Fluent

_with

Constructor Detail

CoroutineStep

protected CoroutineStep()

Creates a new instance.

Method Detail

runAsync

public void runAsync(java.util.concurrent.CompletableFuture<I> fPreviousExecution,
                     CoroutineStep<O,?> rNextStep,
                     Continuation<?> rContinuation)

Runs this execution step asynchronously as a continuation of a previous code execution in a CompletableFuture and proceeds to the next step afterwards.

Subclasses that need to suspend the invocation of the next step until some condition is met (e.g. sending or receiving data has finished) need to override this method and create a Suspension by invoking Continuation.suspend(CoroutineStep, CoroutineStep) on the next step. If the condition that caused the suspension resolves the coroutine execution can be resumed by calling Suspension.resume(Object).

Subclasses that override this method also need to handle errors by terminating any further execution (i.e. not resuming a suspension if such exists) and forwarding the causing exception to Continuation.fail(Throwable).

Parameters:

fPreviousExecution - The future of the previous code execution

rNextStep - The next step to execute or NULL for none

rContinuation - The continuation of the execution

runBlocking

public O runBlocking(I rInput,
                     Continuation<?> rContinuation)

Runs this execution immediately, blocking the current thread until the execution finishes.

Parameters:

rInput - The input value

rContinuation - The continuation of the execution

Returns:

The execution result

toString

public java.lang.String toString()

Overrides:

toString in class org.obrel.core.RelatedObject

execute

protected abstract O execute(I rInput,
                             Continuation<?> rContinuation)

This method must be implemented by subclasses to provide the actual functionality of this step.

Parameters:

rInput - The input value

rContinuation - The continuation of the execution

Returns:

The result of the execution

fail

protected O fail(java.lang.Throwable eError,
                 Continuation<?> rContinuation)

Signals an execution failure to the given continuation. This method should be invoked by subclasses the encounter an exception during execution. The return value is always NULL but the method signature is suitable to be used for invocation in a lambda expression as the argument to CompletableFuture.exceptionally(java.util.function.Function).

Parameters:

eError - The exception that occurred

rContinuation - The continuation

Returns:

Always NULL, but with the type of the coroutine result

terminateCoroutine

protected void terminateCoroutine(Continuation<?> rContinuation)

Allow subclasses to terminate the coroutine they currently run in.

Parameters:

rContinuation - The continuation of the current execution