Interface ExecHarness

  • All Superinterfaces:
    java.lang.AutoCloseable

    public interface ExecHarness
    extends java.lang.AutoCloseable
    A utility for testing asynchronous support/service code.

    An execution harness is backed by a thread pool. It is important to call close() when the object is no longer needed to shutdown this thread pool. Alternatively, if you are performing a single operation you can use one of the *single static methods.

    See Also:
    yield(Function), yieldSingle(Function), run(Action), runSingle(Action)
    • Method Detail

      • harness

        static ExecHarness harness()
        Creates a new execution harness.
        
         import ratpack.exec.Promise;
         import ratpack.test.exec.ExecHarness;
         import ratpack.exec.ExecResult;
        
         import static org.junit.Assert.assertEquals;
        
         public class Example {
        
           // An async callback based API
           static class AsyncApi {
        
             static interface Callback<T> {
               void receive(T value);
             }
        
             public <T> void returnAsync(T value, Callback<? super T> callback) {
               new Thread(() -> callback.receive(value)).run();
             }
           }
        
           // Our service class that wraps the raw async API
           // In the real app this is created by the DI container (e.g. Guice)
           static class AsyncService {
             private final AsyncApi asyncApi = new AsyncApi();
        
             // Our method under test
             public <T> Promise<T> promise(final T value) {
               return Promise.async(downstream -> asyncApi.returnAsync(value, downstream::success));
             }
           }
        
           public static void main(String[] args) throws Throwable {
             // the harness must be close()'d when finished with to free resources
             try (ExecHarness harness = ExecHarness.harness()) {
        
               // set up the code under test
               final AsyncService service = new AsyncService();
        
               // exercise the async code using the harness, blocking until the promised value is available
               ExecResult<String> result = harness.yield(execution -> service.promise("foo"));
        
               assertEquals("foo", result.getValue());
             }
           }
         }
         
        When using Ratpack's RxJava integration, ExecHarness can be used to test rx.Observable instances by first converting them to a promise. See the ratpack.rx2.RxRatpack.single(Observable) documentation for an example of testing observables.
        Returns:
        a new execution harness
      • harness

        static ExecHarness harness​(int numThreads)
      • yield

        default <T> ExecResult<T> yield​(Function<? super Execution,​? extends Promise<T>> func)
                                 throws java.lang.Exception
        Synchronously returns a promised value.

        The given function will execute in a separate thread. The calling thread will block, waiting for the promised value to be provided.

        Type Parameters:
        T - the type of promised value
        Parameters:
        func - a function that exercises some code that returns a promise
        Returns:
        the result of the execution
        Throws:
        java.lang.Exception - any thrown by the function
      • yield

        <T> ExecResult<T> yield​(Action<? super RegistrySpec> registry,
                                Function<? super Execution,​? extends Promise<T>> func)
                         throws java.lang.Exception
        Synchronously returns a promised value.

        The given function will execute in a separate thread. The calling thread will block, waiting for the promised value to be provided.

        Type Parameters:
        T - the type of promised value
        Parameters:
        registry - the intial contents of the execution registry
        func - a function that exercises some code that returns a promise
        Returns:
        the result of the execution
        Throws:
        java.lang.Exception - any thrown by the function
      • yieldSingle

        static <T> ExecResult<T> yieldSingle​(Function<? super Execution,​? extends Promise<T>> func)
                                      throws java.lang.Exception
        Creates an exec harness, executes the given function with it before closing it, then returning execution result.
        Type Parameters:
        T - the type of promised value
        Parameters:
        func - a function that exercises some code that returns a promise
        Returns:
        the result of the execution
        Throws:
        java.lang.Exception - any thrown by the function, or the promise failure exception
      • yieldSingle

        static <T> ExecResult<T> yieldSingle​(Action<? super RegistrySpec> registry,
                                             Function<? super Execution,​? extends Promise<T>> func)
                                      throws java.lang.Exception
        Creates an exec harness, executes the given function with it before closing it, then returning execution result.
        Type Parameters:
        T - the type of promised value
        Parameters:
        registry - the intial contents of the execution registry
        func - a function that exercises some code that returns a promise
        Returns:
        the result of the execution
        Throws:
        java.lang.Exception - any thrown by the function, or the promise failure exception
      • run

        default void run​(Action<? super Execution> action)
                  throws java.lang.Exception
        Initiates an execution and blocks until it completes. If an uncaught exception is thrown during the execution, it will be thrown by this method.

        This method is useful for testing an execution that has some detectable side effect, as this method does not return the “result” of the execution.

        Parameters:
        action - the start of the execution
        Throws:
        java.lang.Exception - any thrown during the execution that is not explicitly caught
        See Also:
        runSingle(Action), yield(Function)
      • run

        void run​(Action<? super RegistrySpec> registry,
                 Action<? super Execution> action)
          throws java.lang.Exception
        Initiates an execution and blocks until it completes. If an uncaught exception is thrown during the execution, it will be thrown by this method.

        This method is useful for testing an execution that has some detectable side effect, as this method does not return the “result” of the execution.

        Parameters:
        registry - the intial contents of the execution registry
        action - the start of the execution
        Throws:
        java.lang.Exception - any thrown during the execution that is not explicitly caught
        See Also:
        runSingle(Action), yield(Function)
      • runSingle

        static void runSingle​(Action<? super Execution> action)
                       throws java.lang.Exception
        Convenient form of run(Action) that creates and closes a harness for the run.
        Parameters:
        action - the start of the execution
        Throws:
        java.lang.Exception - any thrown during the execution that is not explicitly caught
        See Also:
        run(Action), yield(Function)
      • runSingle

        static void runSingle​(Action<? super RegistrySpec> registry,
                              Action<? super Execution> action)
                       throws java.lang.Exception
        Convenient form of run(Action, Action) that creates and closes a harness for the run.
        Parameters:
        registry - the intial contents of the execution registry
        action - the start of the execution
        Throws:
        java.lang.Exception - any thrown during the execution that is not explicitly caught
        See Also:
        run(Action), yield(Function)
      • execute

        default void execute​(Function<? super Execution,​? extends Operation> function)
                      throws java.lang.Exception
        Throws:
        java.lang.Exception
      • execute

        default void execute​(Operation operation)
                      throws java.lang.Exception
        Throws:
        java.lang.Exception
      • executeSingle

        static void executeSingle​(Function<? super Execution,​? extends Operation> function)
                           throws java.lang.Exception
        Throws:
        java.lang.Exception
      • executeSingle

        static void executeSingle​(Operation operation)
                           throws java.lang.Exception
        Throws:
        java.lang.Exception
      • close

        void close()
        Shuts down the thread pool backing this harness.
        Specified by:
        close in interface java.lang.AutoCloseable