public interface Chain
The GroovyChain
type does not represent the handlers "in action".
That is, it is the construction of a handler chain.
A chain can be constructed using the Handlers.chain(LaunchConfig, ratpack.func.Action)
like methods.
For example, from a HandlerFactory
implementation…
import ratpack.launch.HandlerFactory; import ratpack.launch.LaunchConfig; import ratpack.handling.Chain; import ratpack.handling.Handler; import ratpack.handling.Handlers; import ratpack.handling.Context; import ratpack.func.Action; public class MyHandlerBootstrap implements HandlerFactory { public Handler create(LaunchConfig launchConfig) { return Handlers.chain(launchConfig, new Action<Chain>() { public void execute(Chain chain) { chain .assets("public") .prefix("api", chain.chain(new Action<Chain>() { public void execute(Chain api) { api .get("people", new PeopleHandler()) .post( "person/:id", new Handler() { public void handle(Context context) { // handle } }); } })); } }); } } public class PeopleHandler implements Handler { public void handle(Context context) { // handle } }
Chains may be backed by a registry
, depending on how the chain was constructed.
For example, the Ratpack Guice module makes it possible to create a Guice backed registry that can be used to
construct dependency injected handlers. See the ratpack-guice
library for details.
A Groovy specific subclass of this interface is provided by the Groovy module that overloads methods here with Closure
based variants.
See the ratpack-groovy
library for details.
Modifier and Type | Method and Description |
---|---|
Chain |
assets(String path,
String... indexFiles)
Adds a handler that serves static assets at the given file system path, relative to the contextual file system binding.
|
Handler |
chain(Action<? super Chain> action)
Constructs a handler using the given action to define a chain.
|
Chain |
delete(Handler handler)
Adds a handler that delegates to the given handler if
the
request HTTPMethod is DELETE and the path is at the current root. |
Chain |
delete(String path,
Handler handler)
Adds a handler that delegates to the given handler if
the relative
path matches the given path and the request HTTPMethod
is DELETE . |
Chain |
fileSystem(String path,
Action<? super Chain> action)
Adds a handler to this chain that changes the
FileSystemBinding for the given handler chain. |
Chain |
fileSystem(String path,
Handler handler)
Adds a handler to this chain that changes the
FileSystemBinding for the given handler. |
Chain |
get(Handler handler)
Adds a handler that delegates to the given handler
if the
request HTTPMethod is GET and the path is at the
current root. |
Chain |
get(String path,
Handler handler)
Adds a handler that delegates to the given handler
if the relative
path matches the given path and the request
HTTPMethod is GET . |
LaunchConfig |
getLaunchConfig()
The launch config of the application that this chain is being created for.
|
Registry |
getRegistry()
The registry that backs this.
|
Chain |
handler(Handler handler)
Adds the given handler to this.
|
Chain |
handler(String path,
Handler handler)
Adds a handler that delegates to the given handler if the relative
path
matches the given path exactly. |
Chain |
header(String headerName,
String headerValue,
Handler handler)
Adds a handler to the chain that delegates to the given handler if the request has a header with the given name and a its value matches the given value exactly.
|
Chain |
host(String hostName,
Action<? super Chain> action)
Adds a handler to the chain that delegates to the given handler chain if the request has a
Host header that matches the given value exactly. |
Chain |
insert(Action<? super Chain> action)
Inserts the given nested handler chain.
|
Chain |
patch(Handler handler)
Adds a handler that delegates to the given handler if
the
request HTTPMethod is PATCH and the path is at the current root. |
Chain |
patch(String path,
Handler handler)
Adds a handler that delegates to the given handler if
the relative
path matches the given path and the request HTTPMethod
is PATCH . |
Chain |
post(Handler handler)
Adds a handler that delegates to the given handler if
the
request HTTPMethod is POST and the path is at the current root. |
Chain |
post(String path,
Handler handler)
Adds a handler that delegates to the given handler if
the relative
path matches the given path and the request HTTPMethod
is POST . |
Chain |
prefix(String prefix,
Action<? super Chain> action)
Adds a handler that delegates to the given handlers if the
relative path starts with the given
prefix . |
Chain |
prefix(String prefix,
Handler handler)
Adds a handler that delegates to the given handler if the relative path starts with the given
prefix . |
Chain |
put(Handler handler)
Adds a handler that delegates to the given handler if
the
request HTTPMethod is PUT and the path is at the current root. |
Chain |
put(String path,
Handler handler)
Adds a handler that delegates to the given handler if
the relative
path matches the given path and the request HTTPMethod
is PUT . |
Chain |
redirect(int code,
String location)
Sends an HTTP redirect to the specified location.
|
Chain |
register(Action<? super RegistrySpec> action)
Builds a new registry via the given action, then registers it via
register(Registry) . |
Chain |
register(Action<? super RegistrySpec> registryAction,
Action<? super Chain> action)
Adds a handler that inserts the given handler chain with a registry built by the given action via
Context.insert(ratpack.registry.Registry, Handler...) . |
Chain |
register(Action<? super RegistrySpec> registryAction,
Handler handler)
Adds a handler that inserts the given handler with the a registry built by the given action via
Context.insert(ratpack.registry.Registry, Handler...) . |
Chain |
register(Registry registry)
Makes the contents of the given registry available for downstream handlers of the same nesting level.
|
Chain |
register(Registry registry,
Action<? super Chain> action)
Adds a handler that inserts the given handler chain with the given registry via
Context.insert(ratpack.registry.Registry, Handler...) . |
Chain |
register(Registry registry,
Handler handler)
Adds a handler that inserts the given handler with the given registry via
Context.insert(ratpack.registry.Registry, Handler...) . |
Chain assets(String path, String... indexFiles)
See Handlers.assets(LaunchConfig, String, java.util.List)
for more details on the handler created
prefix("foo") { assets("d1", "index.html", "index.xhtml") }In the above configuration a request like "/foo/app.js" will return the static file "app.js" that is located in the directory "d1".
If the request matches a directory e.g. "/foo", an index file may be served. The indexFiles
array specifies the names of files to look for in order to serve.
path
- the relative path to the location of the assets to serveindexFiles
- the index files to try if the request is for a directoryHandler chain(Action<? super Chain> action) throws Exception
action
- The action that defines the handler chainException
- any thrown by action
Chain delete(String path, Handler handler)
path
matches the given path
and the request
HTTPMethod
is DELETE
.path
- the relative path to match onhandler
- the handler to delegate toget(String, Handler)
,
post(String, Handler)
,
put(String, Handler)
,
patch(String, Handler)
,
handler(String, Handler)
Chain delete(Handler handler)
request
HTTPMethod
is DELETE
and the path
is at the current root.handler
- the handler to delegate toget(Handler)
,
post(Handler)
,
put(Handler)
,
patch(Handler)
Chain fileSystem(String path, Handler handler)
FileSystemBinding
for the given handler.path
- the relative path to the new file system binding pointhandler
- the handlerChain fileSystem(String path, Action<? super Chain> action) throws Exception
FileSystemBinding
for the given handler chain.path
- the relative path to the new file system binding pointaction
- the definition of the handler chainException
- any thrown by action
Chain get(String path, Handler handler)
path
matches the given path
and the request
HTTPMethod
is GET
.
path
- the relative path to match onhandler
- the handler to delegate topost(String, Handler)
,
put(String, Handler)
,
patch(String, Handler)
,
delete(String, Handler)
,
handler(String, Handler)
Chain get(Handler handler)
request
HTTPMethod
is GET
and the path
is at the
current root.handler
- the handler to delegate topost(Handler)
,
put(Handler)
,
patch(Handler)
,
delete(Handler)
LaunchConfig getLaunchConfig()
@Nullable Registry getRegistry()
The registry that is available is dependent on how the GroovyChain
was constructed.
null
if this has no registry.Handlers.chain(LaunchConfig, Registry, ratpack.func.Action)
Chain handler(Handler handler)
handler
- the handler to addChain handler(String path, Handler handler)
path
matches the given path
exactly.
Nesting path
handlers will not work due to the exact matching, use a combination of path
and prefix
instead. See prefix(String, Handler)
for details.
// this will not work path("person/:id") { path("child/:childId") { // a request of /person/2/child/1 will not get passed the first handler as it will try // to match "person/2/child/1" with "person/2" which does not match } // this will work prefix("person/:id") { path("child/:childId") { // a request of /person/2/child/1 will work this time } }
See Handlers.path(String, Handler)
for the details on how path
is interpreted.
path
- the relative path to match exactly onhandler
- the handler to delegate topost(String, Handler)
,
get(String, Handler)
,
put(String, Handler)
,
patch(String, Handler)
,
delete(String, Handler)
Chain header(String headerName, String headerValue, Handler handler)
chain. header("foo", "bar", new Handler() { public void handle(Context context) { context.getResponse().send("Header Handler"); } });
headerName
- the name of the HTTP Header to match onheaderValue
- the value of the HTTP Header to match onhandler
- the handler to delegate toChain host(String hostName, Action<? super Chain> action) throws Exception
Host
header that matches the given value exactly.
chain. host("foo.com", new Action<Chain>() { public void execute(Chain hostChain) { hostChain.handler(new Handler() { public void handle(Context context) { context.getResponse().send("Host Handler"); } }); } });
hostName
- the name of the HTTP Header to match onaction
- the handler chain to delegate to if the host matchesException
- any thrown by action
Chain patch(String path, Handler handler)
path
matches the given path
and the request
HTTPMethod
is PATCH
.path
- the relative path to match onhandler
- the handler to delegate toget(String, Handler)
,
post(String, Handler)
,
put(String, Handler)
,
delete(String, Handler)
,
handler(String, Handler)
Chain patch(Handler handler)
request
HTTPMethod
is PATCH
and the path
is at the current root.handler
- the handler to delegate toget(Handler)
,
post(Handler)
,
put(Handler)
,
delete(Handler)
Chain post(String path, Handler handler)
path
matches the given path
and the request
HTTPMethod
is POST
.
path
- the relative path to match onhandler
- the handler to delegate toget(String, Handler)
,
put(String, Handler)
,
patch(String, Handler)
,
delete(String, Handler)
,
handler(String, Handler)
Chain post(Handler handler)
request
HTTPMethod
is POST
and the path
is at the current root.
handler
- the handler to delegate toget(Handler)
,
put(Handler)
,
patch(Handler)
,
delete(Handler)
Chain prefix(String prefix, Handler handler)
prefix
.
All path based handlers become relative to the given prefix
.
See Handlers.prefix(String, Handler)
for format details on the prefix
string.
prefix
- the relative path to match onhandler
- the handler to delegate to if the prefix matchesChain prefix(String prefix, Action<? super Chain> action) throws Exception
prefix
.
All path based handlers become relative to the given prefix
.
chain .prefix("person/:id", new Action<Chain>() { public void execute(Chain personChain) { personChain .get("info", new Handler() { public void handle(Context context) { // e.g. /person/2/info } }) .post("save", new Handler() { public void handle(Context context) { // e.g. /person/2/save } }) .prefix("child/:childId", new Action<Chain>() { public void execute(Chain childChain) { childChain .get("info", new Handler() { public void handle(Context context) { // e.g. /person/2/child/1/info } }); } }); } });
See Handlers.prefix(String, Handler)
for format details on the prefix
string.
prefix
- the relative path to match onaction
- the handler chain to delegate to if the prefix matchesException
- any thrown by action
Chain put(String path, Handler handler)
path
matches the given path
and the request
HTTPMethod
is PUT
.path
- the relative path to match onhandler
- the handler to delegate toget(String, Handler)
,
post(String, Handler)
,
patch(String, Handler)
,
delete(String, Handler)
,
handler(String, Handler)
Chain put(Handler handler)
request
HTTPMethod
is PUT
and the path
is at the current root.handler
- the handler to delegate toget(Handler)
,
post(Handler)
,
patch(Handler)
,
delete(Handler)
Chain register(Registry registry)
The registry is inserted via the Context.next(Registry)
method.
registry
- the registry whose contents should be made available to downstream handlersChain register(Action<? super RegistrySpec> action) throws Exception
register(Registry)
.action
- the definition of a registryException
- any thrown by action
Chain register(Registry registry, Handler handler)
Context.insert(ratpack.registry.Registry, Handler...)
.registry
- the registry to inserthandler
- the handler to insertChain register(Registry registry, Action<? super Chain> action) throws Exception
Context.insert(ratpack.registry.Registry, Handler...)
.registry
- the registry to insertaction
- the definition of the handler chainException
- any thrown by action
Chain register(Action<? super RegistrySpec> registryAction, Handler handler) throws Exception
Context.insert(ratpack.registry.Registry, Handler...)
.registryAction
- the definition of the registry to inserthandler
- the handler to insertException
- any thrown by action
Chain register(Action<? super RegistrySpec> registryAction, Action<? super Chain> action) throws Exception
Context.insert(ratpack.registry.Registry, Handler...)
.registryAction
- the definition of the registry to insert]action
- the definition of the handler chainException
- any thrown by action
Chain insert(Action<? super Chain> action) throws Exception
Shorter form of handler(Handler)
handler}(chain
(action
).
action
- the handler chain to insertException
- any thrown by action
Chain redirect(int code, String location)
The handler to add is created via Handlers.redirect(int, String)
.
code
- the 3XX HTTP status code.location
- the URL to set in the Location response headerHandlers.redirect(int, String)