ICompletionStage Interface

Definition

Namespace:

Java.Util.Concurrent

Assembly:

Mono.Android.dll

A stage of a possibly asynchronous computation, that performs an action or computes a value when another CompletionStage completes.

[Android.Runtime.Register("java/util/concurrent/CompletionStage", "", "Java.Util.Concurrent.ICompletionStageInvoker", ApiSince=24)]
[Java.Interop.JavaTypeParameters(new System.String[] { "T" })]
public interface ICompletionStage : Android.Runtime.IJavaObject, IDisposable, Java.Interop.IJavaPeerable

[<Android.Runtime.Register("java/util/concurrent/CompletionStage", "", "Java.Util.Concurrent.ICompletionStageInvoker", ApiSince=24)>]
[<Java.Interop.JavaTypeParameters(new System.String[] { "T" })>]
type ICompletionStage = interface
    interface IJavaObject
    interface IDisposable
    interface IJavaPeerable

Derived

Java.Util.Concurrent.CompletableFuture

Attributes

RegisterAttribute JavaTypeParametersAttribute

Implements

IJavaObject IJavaPeerable IDisposable

Remarks

A stage of a possibly asynchronous computation, that performs an action or computes a value when another CompletionStage completes. A stage completes upon termination of its computation, but this may in turn trigger other dependent stages. The functionality defined in this interface takes only a few basic forms, which expand out to a larger set of methods to capture a range of usage styles:

<ul>

<li>The computation performed by a stage may be expressed as a Function, Consumer, or Runnable (using methods with names including <em>apply</em>, <em>accept</em>, or <em>run</em>, respectively) depending on whether it requires arguments and/or produces results. For example:

{@code
            stage.thenApply(x -> square(x))
                 .thenAccept(x -> System.out.print(x))
                 .thenRun(() -> System.out.println());}

An additional form (<em>compose</em>) allows the construction of computation pipelines from functions returning completion stages.

Any argument to a stage's computation is the outcome of a triggering stage's computation.

<li>One stage's execution may be triggered by completion of a single stage, or both of two stages, or either of two stages. Dependencies on a single stage are arranged using methods with prefix <em>then</em>. Those triggered by completion of <em>both</em> of two stages may <em>combine</em> their results or effects, using correspondingly named methods. Those triggered by <em>either</em> of two stages make no guarantees about which of the results or effects are used for the dependent stage's computation.

<li>Dependencies among stages control the triggering of computations, but do not otherwise guarantee any particular ordering. Additionally, execution of a new stage's computations may be arranged in any of three ways: default execution, default asynchronous execution (using methods with suffix <em>async</em> that employ the stage's default asynchronous execution facility), or custom (via a supplied Executor). The execution properties of default and async modes are specified by CompletionStage implementations, not this interface. Methods with explicit Executor arguments may have arbitrary execution properties, and might not even support concurrent execution, but are arranged for processing in a way that accommodates asynchrony.

<li>Two method forms (#handle handle and #whenComplete whenComplete) support unconditional computation whether the triggering stage completed normally or exceptionally. Method #exceptionally exceptionally supports computation only when the triggering stage completes exceptionally, computing a replacement result, similarly to the java catch keyword. In all other cases, if a stage's computation terminates abruptly with an (unchecked) exception or error, then all dependent stages requiring its completion complete exceptionally as well, with a CompletionException holding the exception as its cause. If a stage is dependent on <em>both</em> of two stages, and both complete exceptionally, then the CompletionException may correspond to either one of these exceptions. If a stage is dependent on <em>either</em> of two others, and only one of them completes exceptionally, no guarantees are made about whether the dependent stage completes normally or exceptionally. In the case of method whenComplete, when the supplied action itself encounters an exception, then the stage completes exceptionally with this exception unless the source stage also completed exceptionally, in which case the exceptional completion from the source stage is given preference and propagated to the dependent stage.

</ul>

All methods adhere to the above triggering, execution, and exceptional completion specifications (which are not repeated in individual method specifications). Additionally, while arguments used to pass a completion result (that is, for parameters of type T) for methods accepting them may be null, passing a null value for any other parameter will result in a NullPointerException being thrown.

Method form #handle handle is the most general way of creating a continuation stage, unconditionally performing a computation that is given both the result and exception (if any) of the triggering CompletionStage, and computing an arbitrary result. Method #whenComplete whenComplete is similar, but preserves the result of the triggering stage instead of computing a new one. Because a stage's normal result may be null, both methods should have a computation structured thus:

{@code (result, exception) -> {
              if (exception == null) {
                // triggering stage completed normally
              } else {
                // triggering stage completed exceptionally
              }
            }}

This interface does not define methods for initially creating, forcibly completing normally or exceptionally, probing completion status or results, or awaiting completion of a stage. Implementations of CompletionStage may provide means of achieving such effects, as appropriate. Method #toCompletableFuture enables interoperability among different implementations of this interface by providing a common conversion type.

Added in 1.8.

Java documentation for java.util.concurrent.CompletionStage.

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Properties

Handle	Gets the JNI value of the underlying Android object. (Inherited from IJavaObject)
JniIdentityHashCode	Returns the value of java.lang.System.identityHashCode() for the wrapped instance. (Inherited from IJavaPeerable)
JniManagedPeerState	State of the managed peer. (Inherited from IJavaPeerable)
JniPeerMembers	Member access and invocation support. (Inherited from IJavaPeerable)
PeerReference	Returns a JniObjectReference of the wrapped Java object instance. (Inherited from IJavaPeerable)

Methods

AcceptEither(ICompletionStage, IConsumer)	Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed with the corresponding result as argument to the supplied action.
AcceptEitherAsync(ICompletionStage, IConsumer)	Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using this stage's default asynchronous execution facility, with the corresponding result as argument to the supplied action.
AcceptEitherAsync(ICompletionStage, IConsumer, IExecutor)	Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied action.
ApplyToEither(ICompletionStage, IFunction)	Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed with the corresponding result as argument to the supplied function.
ApplyToEitherAsync(ICompletionStage, IFunction)	Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using this stage's default asynchronous execution facility, with the corresponding result as argument to the supplied function.
ApplyToEitherAsync(ICompletionStage, IFunction, IExecutor)	Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied function.
Disposed()	Called when the instance has been disposed. (Inherited from IJavaPeerable)
DisposeUnlessReferenced()	If there are no outstanding references to this instance, then calls Dispose(); otherwise, does nothing. (Inherited from IJavaPeerable)
Exceptionally(IFunction)	Returns a new CompletionStage that, when this stage completes exceptionally, is executed with this stage's exception as the argument to the supplied function.
ExceptionallyAsync(IFunction)	Returns a new CompletionStage that, when this stage completes exceptionally, is executed with this stage's exception as the argument to the supplied function, using this stage's default asynchronous execution facility.
ExceptionallyAsync(IFunction, IExecutor)	Returns a new CompletionStage that, when this stage completes exceptionally, is executed with this stage's exception as the argument to the supplied function, using the supplied Executor.
ExceptionallyCompose(IFunction)	Returns a new CompletionStage that, when this stage completes exceptionally, is composed using the results of the supplied function applied to this stage's exception.
ExceptionallyComposeAsync(IFunction)	Returns a new CompletionStage that, when this stage completes exceptionally, is composed using the results of the supplied function applied to this stage's exception, using this stage's default asynchronous execution facility.
ExceptionallyComposeAsync(IFunction, IExecutor)	Returns a new CompletionStage that, when this stage completes exceptionally, is composed using the results of the supplied function applied to this stage's exception, using the supplied Executor.
Finalized()	Called when the instance has been finalized. (Inherited from IJavaPeerable)
Handle(IBiFunction)	Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed with this stage's result and exception as arguments to the supplied function.
HandleAsync(IBiFunction)	Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed using this stage's default asynchronous execution facility, with this stage's result and exception as arguments to the supplied function.
HandleAsync(IBiFunction, IExecutor)	Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed using the supplied executor, with this stage's result and exception as arguments to the supplied function.
RunAfterBoth(ICompletionStage, IRunnable)	Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action.
RunAfterBothAsync(ICompletionStage, IRunnable)	Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using this stage's default asynchronous execution facility.
RunAfterBothAsync(ICompletionStage, IRunnable, IExecutor)	Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using the supplied executor.
RunAfterEither(ICompletionStage, IRunnable)	Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action.
RunAfterEitherAsync(ICompletionStage, IRunnable)	Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action using this stage's default asynchronous execution facility.
RunAfterEitherAsync(ICompletionStage, IRunnable, IExecutor)	Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action using the supplied executor.
SetJniIdentityHashCode(Int32)	Set the value returned by JniIdentityHashCode. (Inherited from IJavaPeerable)
SetJniManagedPeerState(JniManagedPeerStates)	(Inherited from IJavaPeerable)
SetPeerReference(JniObjectReference)	Set the value returned by PeerReference. (Inherited from IJavaPeerable)
ThenAccept(IConsumer)	Returns a new CompletionStage that, when this stage completes normally, is executed with this stage's result as the argument to the supplied action.
ThenAcceptAsync(IConsumer)	Returns a new CompletionStage that, when this stage completes normally, is executed using this stage's default asynchronous execution facility, with this stage's result as the argument to the supplied action.
ThenAcceptAsync(IConsumer, IExecutor)	Returns a new CompletionStage that, when this stage completes normally, is executed using the supplied Executor, with this stage's result as the argument to the supplied action.
ThenAcceptBoth(ICompletionStage, IBiConsumer)	Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed with the two results as arguments to the supplied action.
ThenAcceptBothAsync(ICompletionStage, IBiConsumer)	Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using this stage's default asynchronous execution facility, with the two results as arguments to the supplied action.
ThenAcceptBothAsync(ICompletionStage, IBiConsumer, IExecutor)	Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied action.
ThenApply(IFunction)	Returns a new CompletionStage that, when this stage completes normally, is executed with this stage's result as the argument to the supplied function.
ThenApplyAsync(IFunction)	Returns a new CompletionStage that, when this stage completes normally, is executed using this stage's default asynchronous execution facility, with this stage's result as the argument to the supplied function.
ThenApplyAsync(IFunction, IExecutor)	Returns a new CompletionStage that, when this stage completes normally, is executed using the supplied Executor, with this stage's result as the argument to the supplied function.
ThenCombine(ICompletionStage, IBiFunction)	Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed with the two results as arguments to the supplied function.
ThenCombineAsync(ICompletionStage, IBiFunction)	Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using this stage's default asynchronous execution facility, with the two results as arguments to the supplied function.
ThenCombineAsync(ICompletionStage, IBiFunction, IExecutor)	Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied function.
ThenCompose(IFunction)	Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function.
ThenComposeAsync(IFunction)	Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed using this stage's default asynchronous execution facility.
ThenComposeAsync(IFunction, IExecutor)	Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed using the supplied Executor.
ThenRun(IRunnable)	Returns a new CompletionStage that, when this stage completes normally, executes the given action.
ThenRunAsync(IRunnable)	Returns a new CompletionStage that, when this stage completes normally, executes the given action using this stage's default asynchronous execution facility.
ThenRunAsync(IRunnable, IExecutor)	Returns a new CompletionStage that, when this stage completes normally, executes the given action using the supplied Executor.
ToCompletableFuture()	Returns a CompletableFuture maintaining the same completion properties as this stage.
UnregisterFromRuntime()	Unregister this instance so that the runtime will not return it from future Java.Interop.JniRuntime+JniValueManager.PeekValue invocations. (Inherited from IJavaPeerable)
WhenComplete(IBiConsumer)	Returns a new CompletionStage with the same result or exception as this stage, that executes the given action when this stage completes.
WhenCompleteAsync(IBiConsumer)	Returns a new CompletionStage with the same result or exception as this stage, that executes the given action using this stage's default asynchronous execution facility when this stage completes.
WhenCompleteAsync(IBiConsumer, IExecutor)	Returns a new CompletionStage with the same result or exception as this stage, that executes the given action using the supplied Executor when this stage completes.

Extension Methods

JavaCast<TResult>(IJavaObject)	Performs an Android runtime-checked type conversion.
JavaCast<TResult>(IJavaObject)
GetJniTypeName(IJavaPeerable)