Package ratpack.exec

Interface Operation

public interface Operation

A logical operation.

An operation encapsulates a logical piece of work, which will complete some time in the future. It is similar to a Promise except 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. The onError(Action) method allows specifying what should happen if the operation fails. Like Promise, the operation will not start until it is subscribed to, via then(Block) or then().

It is common for methods that would naturally return void to return an Operation instead, to allow the method implementation to be effectively asynchronous. The caller of the method is then expected to use the then(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.jupiter.api.Assertions.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

Modifier and Type	Method	Description
default Operation	blockingNext(Block operation)	Executes the given block as an operation, on a blocking thread.
default <T> Promise<T>	flatMap(Promise<T> promise)
default <T> Promise<T>	flatMap(Factory<? extends Promise<T>> factory)
static Operation	flatten(Factory<Operation> factory)	Create an operation that delegates to another operation.
default <T> Promise<T>	map(Factory<? extends T> factory)
default Operation	mapError(Action<? super Throwable> action)	Convert an error to a success or different error.
default Operation	next(Operation operation)
default Operation	next(Block operation)
static Operation	noop()
static Operation	of(Block block)
default <E extends Throwable> Operation	onError(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 Operation	onError(Action<? super Throwable> onError)
Operation	onError(Predicate<? super Throwable> predicate, Action<? super Throwable> errorHandler)	Specifies the action to take if the an error occurs performing the operation that the given predicate applies to.
Promise<Void>	promise()
default void	then()
void	then(Block block)
default <O> O	to(Function<? super Operation,? extends O> function)
default Operation	wiretap(Action<? super Optional<? extends Throwable>> action)

Method Detail

of

static Operation of(Block block)

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

onError

default Operation onError(Action<? super Throwable> onError)

onError

Operation onError(Predicate<? super Throwable> predicate,
                  Action<? super 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 error

errorHandler - the action to take if an error occurs

Returns:

An operation for the successful result

Since:

1.9

onError

default <E extends Throwable> Operation onError(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 action

errorHandler - the action to take if an error occurs

Returns:

An operation for the successful result

Since:

1.9

mapError

default Operation mapError(Action<? super 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

then

@NonBlocking
void then(Block block)

then

@NonBlocking
default void then()

promise

Promise<Void> promise()

map

default <T> Promise<T> map(Factory<? extends T> factory)

flatMap

default <T> Promise<T> flatMap(Factory<? extends Promise<T>> factory)

flatMap

default <T> Promise<T> flatMap(Promise<T> promise)

next

default Operation next(Operation operation)

next

default Operation next(Block operation)

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 Exception

Throws:

Exception

wiretap

default Operation wiretap(Action<? super Optional<? extends Throwable>> action)

noop

static Operation noop()