Package ratpack.exec

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 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.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 Detail

      • 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​(Action<? super java.lang.Throwable> onError)
      • 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 error
        errorHandler - 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 action
        errorHandler - 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 listener
        after - 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 block
        after - the after block
        Returns:
        an operation
        Since:
        1.10
      • throttled

        default Operation throttled​(Throttle throttle)
        Throttles the operation using the given throttle.

        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 a Result.
        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
      • 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.

        Specified by:
        connect in interface Upstream<java.lang.Void>
        Parameters:
        downstream - the downstream consumer
        Since:
        1.10
      • 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)
        Like close(AutoCloseable), but allows async close operations.
        Parameters:
        closer - the close operation.
        Returns:
        an operation
        Since:
        1.10