public interface MinimalContext extends Registry
Response
or flow control methods.Modifier and Type | Method and Description |
---|---|
<T> SuccessOrErrorPromise<T> |
background(Callable<T> backgroundOperation)
Perform a blocking operation, off the request thread.
|
void |
error(Exception exception)
Forwards the exception to the
ServerErrorHandler in this service. |
Path |
file(String path)
Gets the file relative to the contextual
FileSystemBinding . |
PathTokens |
getAllPathTokens()
The contextual path tokens of the current
PathBinding . |
Background |
getBackground()
An object to be used when executing blocking IO, or long operations.
|
BindAddress |
getBindAddress()
The address that this request was received on.
|
MinimalContext |
getContext()
Returns this.
|
Foreground |
getForeground()
The application foreground.
|
PathTokens |
getPathTokens()
The contextual path tokens of the current
PathBinding . |
Request |
getRequest()
The HTTP request.
|
void |
onClose(Action<? super RequestOutcome> onClose)
Registers a callback to be notified when the request for this context is “closed” (i.e.
|
MinimalContext getContext()
Request getRequest()
@NonBlocking void error(Exception exception) throws NotInRegistryException
ServerErrorHandler
in this service.
The default configuration of Ratpack includes a ServerErrorHandler
in all contexts.
A NotInRegistryException
will only be thrown if a very custom service setup is being used.
exception
- The exception that occurredNotInRegistryException
- if no ServerErrorHandler
can be found in the servicePathTokens getPathTokens() throws NotInRegistryException
PathBinding
.
Shorthand for get(PathBinding.class).getPathTokens()
.
PathBinding
.NotInRegistryException
- if there is no PathBinding
in the current servicePathTokens getAllPathTokens() throws NotInRegistryException
PathBinding
.
Shorthand for get(PathBinding.class).getAllPathTokens()
.
PathBinding
.NotInRegistryException
- if there is no PathBinding
in the current servicePath file(String path) throws NotInRegistryException
FileSystemBinding
.
Shorthand for get(FileSystemBinding.class).file(path)
.
The default configuration of Ratpack includes a FileSystemBinding
in all contexts.
A NotInRegistryException
will only be thrown if a very custom service setup is being used.
path
- The path to pass to the FileSystemBinding.file(String)
method.FileSystemBinding
NotInRegistryException
- if there is no FileSystemBinding
in the current serviceBackground getBackground()
background(java.util.concurrent.Callable)
Foreground getForeground()
Foreground
<T> SuccessOrErrorPromise<T> background(Callable<T> backgroundOperation)
Ratpack apps typically do not use a large thread pool for handling requests. By default there is about one thread per core.
This means that blocking IO operations cannot be done on the thread invokes a handler. Background IO operations must be
offloaded in order to free the request handling thread to handle other requests while the IO operation is performed.
The Background
object makes it easy to do this.
A callable is submitted to the Background.exec(java.util.concurrent.Callable)
method. The implementation of this callable can background
as it will be executed on a non request handling thread. It should do not much more than initiate a blocking IO operation and return the result.
However, the callable is not executed immediately. The return value of Background.exec(java.util.concurrent.Callable)
must be used to specify
how to proceed after the blocking operation. The then()
method must be called for the work to be performed.
import ratpack.handling.Handler; import ratpack.handling.Context; import ratpack.func.Action; import java.util.concurrent.Callable; class MyHandler implements Handler { void handle(final Context context) { context.background(new Callable<String>() { public String call() { // perform some kind of blocking IO in here, such as accessing a database return "foo"; } }).then(new Action<String>() { public void execute(String result) { context.getResponse().send(result); } }); } }
Unless otherwise specified, any exceptions that are raised during the blocking operation callable are forwarded
to the error(Exception)
method of the current context.
Similarly, errors that occur during the result handler are forwarded.
To use a custom error handling strategy, use the SuccessOrErrorPromise.onError(ratpack.func.Action)
method
of the return of Background.exec(java.util.concurrent.Callable)
.
Example usage:
import ratpack.handling.Handler; import ratpack.handling.Context; import ratpack.func.Action; import java.util.concurrent.Callable; class MyHandler implements Handler { void handle(final Context context) { context.background(new Callable<String>() { public String call() { // perform some kind of blocking IO in here, such as accessing a database return "foo"; } }).onError(new Action<Exception>() { public void execute(Exception exception) { // do something with the exception } }).then(new Action<String>() { public void execute(String result) { context.getResponse().send(result); } }); } }
T
- The type of object returned by the background operationbackgroundOperation
- The blocking operation to perform off of the request threadgetBackground()
BindAddress getBindAddress()
void onClose(Action<? super RequestOutcome> onClose)
onClose
- A notification callback