de.esoco.coroutine.step

Class Collect<I,O>

java.lang.Object

org.obrel.core.RelatedObject

de.esoco.coroutine.CoroutineStep<I,java.util.Collection<O>>

de.esoco.coroutine.step.Collect<I,O>

All Implemented Interfaces:

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

public class Collect<I,O>
extends CoroutineStep<I,java.util.Collection<O>>

A coroutine step that suspends the coroutine execution until the results of several other asynchronously executed coroutines are available. The results are then collected and handed over to the resuming step. By default the results of all finished coroutines will be collected but that can be modified by setting a different condition with when(Predicate). Also by default all coroutines will be awaited before resuming but that can be controlled with until(Predicate). If the collecting is finished all coroutines that are still running will be cancelled.

To select exactly only one result from multiple coroutines the related step implementation Select can be used.

Constructor Summary

Constructors

Constructor and Description
Collect(java.util.Collection<Coroutine<? super I,? extends O>> rFromCoroutines) Creates a new instance.

Method Summary

Modifier and Type	Method and Description
Collect<I,O>	and(Coroutine<? super I,? extends O> rCoroutine) Creates a new instance that collects the result of an additional coroutine.
Collect<I,O>	and(CoroutineStep<? super I,? extends O> rStep) Creates a new instance that collects the result of an additional step.
static <I,O> Collect<I,O>	collect(Coroutine<? super I,? extends O>... rFromCoroutines) Suspends the coroutine execution until all coroutines finish and then resumes the execution with a collection of the results.
static <I,O> Collect<I,O>	collect(CoroutineStep<? super I,? extends O>... rFromSteps) Suspends the coroutine execution until one coroutine step finishes.
protected java.util.Collection<O>	execute(I rInput, Continuation<?> rContinuation) This method must be implemented by subclasses to provide the actual functionality of this step.
void	runAsync(java.util.concurrent.CompletableFuture<I> fPreviousExecution, CoroutineStep<java.util.Collection<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.
Collect<I,O>	until(java.util.function.Predicate<Continuation<?>> pCompletionCriteria) Adds a condition for the termination of the result collection.
Collect<I,O>	when(java.util.function.Predicate<Continuation<?>> pCollectCriteria) Adds a condition for the result collection.

Methods inherited from class de.esoco.coroutine.CoroutineStep

fail, runBlocking, terminateCoroutine, 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

Collect

public Collect(java.util.Collection<Coroutine<? super I,? extends O>> rFromCoroutines)

Creates a new instance.

Parameters:

rFromCoroutines - The coroutines to select from

Method Detail

collect

@SafeVarargs
public static <I,O> Collect<I,O> collect(Coroutine<? super I,? extends O>... rFromCoroutines)

Suspends the coroutine execution until all coroutines finish and then resumes the execution with a collection of the results. By default the result of the first finished coroutine is collected. That can be modified by providing a different selection condition to until(Predicate) which will return a new Collect instance. Modified instances that select from additional coroutines or steps can be created with and(Coroutine) and and(CoroutineStep).

Parameters:

rFromCoroutines - The coroutines to select from

Returns:

A new step instance

collect

@SafeVarargs
public static <I,O> Collect<I,O> collect(CoroutineStep<? super I,? extends O>... rFromSteps)

Suspends the coroutine execution until one coroutine step finishes. The step arguments will be wrapped into new coroutines and then handed to collect(Coroutine...).

Parameters:

rFromSteps - The coroutine steps to select from

Returns:

A new step instance

and

public Collect<I,O> and(Coroutine<? super I,? extends O> rCoroutine)

Creates a new instance that collects the result of an additional coroutine.

Parameters:

rCoroutine - The additional coroutine to select from

Returns:

The new instance

and

public Collect<I,O> and(CoroutineStep<? super I,? extends O> rStep)

Creates a new instance that collects the result of an additional step. The step will be wrapped into a new coroutine and handed to and(Coroutine).

Parameters:

rStep - The additional step to select from

Returns:

The new instance

runAsync

public void runAsync(java.util.concurrent.CompletableFuture<I> fPreviousExecution,
                     CoroutineStep<java.util.Collection<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).

Overrides:

runAsync in class CoroutineStep<I,java.util.Collection<O>>

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

until

public Collect<I,O> until(java.util.function.Predicate<Continuation<?>> pCompletionCriteria)

Adds a condition for the termination of the result collection. If a succefully finished continuation matches the given predicate the collection will be completed and the suspension resumed with the result that has been collected so far.

Any collection criteria provided through when(Predicate) are not automatically applied to the completion criteria and must therefore be handled explicitly in the completion test if necessary.

Parameters:

pCompletionCriteria - A condition that checks if a result should be selected

Returns:

A new step instance

when

public Collect<I,O> when(java.util.function.Predicate<Continuation<?>> pCollectCriteria)

Adds a condition for the result collection. If a succefully finished continuation matches the given predicate it will be collected into the step result.

Parameters:

pCollectCriteria - A condition that checks if a result should be collected

Returns:

A new step instance

execute

protected java.util.Collection<O> execute(I rInput,
                                          Continuation<?> rContinuation)

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

Specified by:

execute in class CoroutineStep<I,java.util.Collection<O>>

Parameters:

rInput - The input value

rContinuation - The continuation of the execution

Returns:

The result of the execution