Interface Operation
-
- All Superinterfaces:
Upstream<java.lang.Void>
@NonBlocking public interface Operation extends Upstream<java.lang.Void>
A logical operation.An operation encapsulates a logical piece of work, which will complete some time in the future. It is similar to a
Promiseexcept that it does not produce a value. It merely succeeds, or throws an exception.The
then(Block)method allows specifying what should happen after the operation completes. TheonError(Action)method allows specifying what should happen if the operation fails. LikePromise, the operation will not start until it is subscribed to, viathen(Block)orthen().It is common for methods that would naturally return
voidto return anOperationinstead, to allow the method implementation to be effectively asynchronous. The caller of the method is then expected to use thethen(Block)method to specify what should happen after the operation that the method represents finishes.import ratpack.exec.Blocking; import ratpack.exec.Operation; import com.google.common.collect.Lists; import ratpack.test.exec.ExecHarness; import java.util.Arrays; import java.util.List; import static org.junit.Assert.assertEquals; public class Example { public static void main(String... args) throws Exception { List<String> events = Lists.newArrayList(); ExecHarness.runSingle(e -> Operation.of(() -> Blocking.get(() -> events.add("1")) .then(b -> events.add("2")) ) .then(() -> events.add("3")) ); assertEquals(Arrays.asList("1", "2", "3"), events); } }
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default Operationaround(java.lang.Runnable before, Function<? super ExecResult<java.lang.Void>,? extends ExecResult<java.lang.Void>> after)Facilitates intercepting an operation before and after.default Operationaround(Block before, Block after)Facilitates executing something before a promise is yielded and after it has completed.static Operationasync(Upstream<java.lang.Void> upstream)default OperationblockingNext(Block operation)Executes the given block as an operation, on a blocking thread.default Operationclose(java.lang.AutoCloseable closeable)Closes the given closeable control flows to this point.default Operationclose(Operation closer)Likeclose(AutoCloseable), but allows async close operations.voidconnect(Downstream<? super java.lang.Void> downstream)A low level hook for consuming the promised value.static Operationerror(java.lang.Throwable error)Create an operation that fails with the given throwabledefault <T> Promise<T>flatMap(Promise<T> promise)default <T> Promise<T>flatMap(Factory<? extends Promise<T>> factory)static Operationflatten(Factory<Operation> factory)Create an operation that delegates to another operation.default <T> Promise<T>map(Factory<? extends T> factory)default OperationmapError(Action<? super java.lang.Throwable> action)Convert an error to a success or different error.default Operationnext(Operation operation)default Operationnext(Block operation)static Operationnoop()static Operationof(Block block)default <E extends java.lang.Throwable>
OperationonError(java.lang.Class<E> errorType, Action<? super E> errorHandler)Specifies the action to take if the an error of the given type occurs trying to perform the operation.default OperationonError(Action<? super java.lang.Throwable> onError)default OperationonError(Predicate<? super java.lang.Throwable> predicate, Action<? super java.lang.Throwable> errorHandler)Specifies the action to take if the an error occurs performing the operation that the given predicate applies to.default OperationonYield(java.lang.Runnable onYield)Registers a listener that is invoked when the operation is initiated.Promise<java.lang.Void>promise()default Promise<ExecResult<java.lang.Void>>result()Create a promise for an exec result of this promise.default voidresult(Action<? super ExecResult<java.lang.Void>> resultHandler)Consume the operation as aResult.default voidthen()voidthen(Block block)default Operationthrottled(Throttle throttle)Throttles the operation using the giventhrottle.default <O> Oto(Function<? super Operation,? extends O> function)Operationtransform(Function<? super Upstream<java.lang.Void>,? extends Upstream<java.lang.Void>> upstreamTransformer)default Operationwiretap(Action<? super java.util.Optional<? extends java.lang.Throwable>> result)Listens for the operation outcome.
-
-
-
Method Detail
-
noop
static Operation noop()
-
flatten
static Operation flatten(Factory<Operation> factory)
Create an operation that delegates to another operation.- Parameters:
factory- a factory for the operation- Returns:
- an operation
- Since:
- 1.5
-
error
static Operation error(java.lang.Throwable error)
Create an operation that fails with the given throwable- Parameters:
error- the error- Returns:
- an operation
- Since:
- 1.10
-
onError
default Operation onError(Predicate<? super java.lang.Throwable> predicate, Action<? super java.lang.Throwable> errorHandler)
Specifies the action to take if the an error occurs performing the operation that the given predicate applies to.If the given action throws an exception, the original exception will be rethrown with the exception thrown by the action added to the suppressed exceptions list.
- Parameters:
predicate- the predicate to test against the errorerrorHandler- the action to take if an error occurs- Returns:
- An operation for the successful result
- Since:
- 1.9
-
onError
default <E extends java.lang.Throwable> Operation onError(java.lang.Class<E> errorType, Action<? super E> errorHandler)
Specifies the action to take if the an error of the given type occurs trying to perform the operation.If the given action throws an exception, the original exception will be rethrown with the exception thrown by the action added to the suppressed exceptions list.
- Type Parameters:
E- the type of exception to handle with the given action- Parameters:
errorType- the type of exception to handle with the given actionerrorHandler- the action to take if an error occurs- Returns:
- An operation for the successful result
- Since:
- 1.9
-
mapError
default Operation mapError(@NonBlocking Action<? super java.lang.Throwable> action)
Convert an error to a success or different error.The given action receives the upstream error and is executed as an operation. If the operation completes without error, the original error is considered handled and the returned operation will propagate success.
If the given action operation throws an exception, the returned operation will propagate that exception.
This method differs to
onError(Action)in that it does not terminate the operation.- Parameters:
action- the error handler- Returns:
- an operation
- Since:
- 1.5
-
onYield
default Operation onYield(java.lang.Runnable onYield)
Registers a listener that is invoked when the operation is initiated.- Parameters:
onYield- the action to take when the operation is initiated- Returns:
- the operation
- Since:
- 1.10
-
around
default Operation around(java.lang.Runnable before, Function<? super ExecResult<java.lang.Void>,? extends ExecResult<java.lang.Void>> after)
Facilitates intercepting an operation before and after.- Parameters:
before- the before listenerafter- the after listener- Returns:
- an operation
- Since:
- 1.10
-
around
default Operation around(Block before, Block after)
Facilitates executing something before a promise is yielded and after it has completed.- Parameters:
before- the before blockafter- the after block- Returns:
- an operation
- Since:
- 1.10
-
throttled
default Operation throttled(Throttle throttle)
Throttles the operation using the giventhrottle.Throttling can be used to limit concurrency. Typically, to limit concurrent use of an external resource, such as a HTTP API.
- Parameters:
throttle- the particular throttle to use to throttle the operation- Returns:
- the throttled operation
- Since:
- 1.10
-
result
default void result(Action<? super ExecResult<java.lang.Void>> resultHandler)
Consume the operation as aResult.- Parameters:
resultHandler- the consumer of the result- Since:
- 1.10
-
result
default Promise<ExecResult<java.lang.Void>> result()
Create a promise for an exec result of this promise.- Since:
- 1.10
-
then
void then(Block block)
-
then
default void then()
-
promise
Promise<java.lang.Void> promise()
-
blockingNext
default Operation blockingNext(Block operation)
Executes the given block as an operation, on a blocking thread.- Parameters:
operation- a block of code to be executed, on a blocking thread- Returns:
- an operation
- Since:
- 1.4
-
to
default <O> O to(Function<? super Operation,? extends O> function) throws java.lang.Exception
- Throws:
java.lang.Exception
-
wiretap
default Operation wiretap(Action<? super java.util.Optional<? extends java.lang.Throwable>> result)
Listens for the operation outcome.- Parameters:
result- an empty optional if the operation succeeds, or an optional of the operation error.- Returns:
- an operation
- Since:
- 1.6
-
transform
Operation transform(Function<? super Upstream<java.lang.Void>,? extends Upstream<java.lang.Void>> upstreamTransformer)
-
connect
void connect(Downstream<? super java.lang.Void> downstream)
A low level hook for consuming the promised value.It is generally preferable to use
then()over this method.
-
close
default Operation close(java.lang.AutoCloseable closeable)
Closes the given closeable control flows to this point.This can be used to simulate a try/finally synchronous construct. It is typically used to close some resource after an asynchronous operation.
The general pattern is to open the resource, and then pass it to some method/closure that works with it and returns an operation. This method is then called on the returned operation to clean up the resource.
- Parameters:
closeable- the closeable to close- Returns:
- an operation
- Since:
- 1.10
- See Also:
close(Operation)
-
close
default Operation close(Operation closer)
Likeclose(AutoCloseable), but allows async close operations.- Parameters:
closer- the close operation.- Returns:
- an operation
- Since:
- 1.10
-
-