public interface ExecHarness
extends java.lang.AutoCloseable
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.
yield(Function)
,
yieldSingle(Function)
,
run(Action)
,
runSingle(Action)
Modifier and Type | Method and Description |
---|---|
void |
close()
Shuts down the thread pool backing this harness.
|
default void |
execute(Function<? super Execution,? extends Operation> function) |
default void |
execute(Operation operation) |
static void |
executeSingle(Function<? super Execution,? extends Operation> function) |
static void |
executeSingle(Operation operation) |
default ExecStarter |
fork() |
ExecController |
getController() |
static ExecHarness |
harness()
Creates a new execution harness.
|
static ExecHarness |
harness(int numThreads) |
default void |
run(Action<? super Execution> action)
Initiates an execution and blocks until it completes.
|
void |
run(Action<? super RegistrySpec> registry,
Action<? super Execution> action)
Initiates an execution and blocks until it completes.
|
static void |
runSingle(Action<? super Execution> action)
Convenient form of
run(Action) that creates and closes a harness for the run. |
static void |
runSingle(Action<? super RegistrySpec> registry,
Action<? super Execution> action)
Convenient form of
run(Action, Action) that creates and closes a harness for the run. |
<T> ExecResult<T> |
yield(Action<? super RegistrySpec> registry,
Function<? super Execution,? extends Promise<T>> func)
Synchronously returns a promised value.
|
default <T> ExecResult<T> |
yield(Function<? super Execution,? extends Promise<T>> func)
Synchronously returns a promised value.
|
static <T> ExecResult<T> |
yieldSingle(Action<? super RegistrySpec> registry,
Function<? super Execution,? extends Promise<T>> func)
Creates an exec harness,
executes the given function with it before closing it, then returning execution result. |
static <T> ExecResult<T> |
yieldSingle(Function<? super Execution,? extends Promise<T>> func)
Creates an exec harness,
executes the given function with it before closing it, then returning execution result. |
static ExecHarness 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.static ExecHarness harness(int numThreads)
default ExecStarter fork()
ExecController getController()
default <T> ExecResult<T> yield(Function<? super Execution,? extends Promise<T>> func) throws java.lang.Exception
The given function will execute in a separate thread. The calling thread will block, waiting for the promised value to be provided.
T
- the type of promised valuefunc
- a function that exercises some code that returns a promisejava.lang.Exception
- any thrown by the function<T> ExecResult<T> yield(Action<? super RegistrySpec> registry, Function<? super Execution,? extends Promise<T>> func) throws java.lang.Exception
The given function will execute in a separate thread. The calling thread will block, waiting for the promised value to be provided.
T
- the type of promised valueregistry
- the intial contents of the execution registryfunc
- a function that exercises some code that returns a promisejava.lang.Exception
- any thrown by the functionstatic <T> ExecResult<T> yieldSingle(Function<? super Execution,? extends Promise<T>> func) throws java.lang.Exception
executes
the given function with it before closing it, then returning execution result.T
- the type of promised valuefunc
- a function that exercises some code that returns a promisejava.lang.Exception
- any thrown by the function, or the promise failure exceptionstatic <T> ExecResult<T> yieldSingle(Action<? super RegistrySpec> registry, Function<? super Execution,? extends Promise<T>> func) throws java.lang.Exception
executes
the given function with it before closing it, then returning execution result.T
- the type of promised valueregistry
- the intial contents of the execution registryfunc
- a function that exercises some code that returns a promisejava.lang.Exception
- any thrown by the function, or the promise failure exceptiondefault void run(Action<? super Execution> action) throws java.lang.Exception
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.
action
- the start of the executionjava.lang.Exception
- any thrown during the execution that is not explicitly caughtrunSingle(Action)
,
yield(Function)
void run(Action<? super RegistrySpec> registry, Action<? super Execution> action) throws java.lang.Exception
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.
registry
- the intial contents of the execution registryaction
- the start of the executionjava.lang.Exception
- any thrown during the execution that is not explicitly caughtrunSingle(Action)
,
yield(Function)
static void runSingle(Action<? super Execution> action) throws java.lang.Exception
run(Action)
that creates and closes a harness for the run.action
- the start of the executionjava.lang.Exception
- any thrown during the execution that is not explicitly caughtrun(Action)
,
yield(Function)
static void runSingle(Action<? super RegistrySpec> registry, Action<? super Execution> action) throws java.lang.Exception
run(Action, Action)
that creates and closes a harness for the run.registry
- the intial contents of the execution registryaction
- the start of the executionjava.lang.Exception
- any thrown during the execution that is not explicitly caughtrun(Action)
,
yield(Function)
default void execute(Function<? super Execution,? extends Operation> function) throws java.lang.Exception
java.lang.Exception
default void execute(Operation operation) throws java.lang.Exception
java.lang.Exception
static void executeSingle(Function<? super Execution,? extends Operation> function) throws java.lang.Exception
java.lang.Exception
static void executeSingle(Operation operation) throws java.lang.Exception
java.lang.Exception
void close()
close
in interface java.lang.AutoCloseable