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.util.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.util.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 to this GroovyChain that serves static assets at the given file system path,
relative to the contextual file system binding. |
Handler |
chain(Action<? super Chain> action) |
Chain |
delete(Handler handler)
Adds a
Handler to this GroovyChain 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 to this GroovyChain 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) |
Chain |
fileSystem(String path,
Handler handler)
|
Chain |
get(Handler handler)
Adds a
Handler to this GroovyChain 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 to this GroovyChain 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
GroovyChain . |
Chain |
handler(Handler handler)
Adds the given
Handler to this GroovyChain . |
Chain |
handler(String path,
Handler handler)
Adds a
Handler to this GroovyChain 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 |
patch(Handler handler)
Adds a
Handler to this GroovyChain 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 to this GroovyChain 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 to this GroovyChain 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 to this GroovyChain 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) |
Chain |
prefix(String prefix,
Handler handler)
Adds a
Handler to this GroovyChain that delegates to the given handlers if the
relative path starts with the given prefix . |
Chain |
put(Handler handler)
Adds a
Handler to this GroovyChain 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 to this GroovyChain that delegates to the given Handler if
the relative path matches the given path and the request HTTPMethod
is PUT . |
<T> Chain |
register(Class<? super T> type,
T service,
Action<? super Chain> action) |
<T> Chain |
register(Class<? super T> type,
T service,
Handler handler)
Adds a
Handler to this GroovyChain that inserts the given handlers with the given service addition. |
Chain |
register(Object service,
Action<? super Chain> action) |
Chain |
register(Object service,
Handler handler)
Adds a
Handler to this GroovyChain that inserts the given handler with the given service addition. |
@Nullable Registry getRegistry()
GroovyChain
.
The registry that is available is dependent on how the GroovyChain
was constructed.
GroovyChain
, or null
if this GroovyChain
has no registry.Handlers.chain(LaunchConfig, ratpack.registry.Registry, ratpack.util.Action)
LaunchConfig getLaunchConfig()
Chain handler(Handler handler)
Handler
to this GroovyChain
.handler
- the Handler
to addGroovyChain
Chain handler(String path, Handler handler)
Handler
to this GroovyChain
that delegates to the given Handler
if the relative 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 toGroovyChain
post(String, Handler)
,
get(String, Handler)
,
put(String, Handler)
,
patch(String, Handler)
,
delete(String, Handler)
Chain prefix(String prefix, Handler handler)
Handler
to this GroovyChain
that delegates to the given handlers if the
relative path starts with the given prefix
.
All path based handlers become relative to the given prefix
.
chain .prefix("person/:id", chain.chain(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", chain.chain(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 onhandler
- the handler to delegate to if the prefix matchesGroovyChain
Chain get(String path, Handler handler)
Handler
to this GroovyChain
that delegates to the given Handler
if the relative path
matches the given path
and the request
HTTPMethod
is GET
.
path
- the relative path to match onhandler
- the handler to delegate toGroovyChain
post(String, Handler)
,
put(String, Handler)
,
patch(String, Handler)
,
delete(String, Handler)
,
handler(String, Handler)
Chain get(Handler handler)
Handler
to this GroovyChain
that delegates to the given Handler
if the request
HTTPMethod
is GET
and the path
is at the
current root.handler
- the handler to delegate toGroovyChain
post(Handler)
,
put(Handler)
,
patch(Handler)
,
delete(Handler)
Chain post(String path, Handler handler)
Handler
to this GroovyChain
that delegates to the given Handler
if
the relative path
matches the given path
and the request
HTTPMethod
is POST
.
path
- the relative path to match onhandler
- the handler to delegate toGroovyChain
get(String, Handler)
,
put(String, Handler)
,
patch(String, Handler)
,
delete(String, Handler)
,
handler(String, Handler)
Chain post(Handler handler)
Handler
to this GroovyChain
that delegates to the given Handler
if
the request
HTTPMethod
is POST
and the path
is at the current root.
handler
- the handler to delegate toGroovyChain
get(Handler)
,
put(Handler)
,
patch(Handler)
,
delete(Handler)
Chain put(String path, Handler handler)
Handler
to this GroovyChain
that delegates to the given Handler
if
the relative path
matches the given path
and the request
HTTPMethod
is PUT
.path
- the relative path to match onhandler
- the handler to delegate toGroovyChain
get(String, Handler)
,
post(String, Handler)
,
patch(String, Handler)
,
delete(String, Handler)
,
handler(String, Handler)
Chain put(Handler handler)
Handler
to this GroovyChain
that delegates to the given Handler
if
the request
HTTPMethod
is PUT
and the path
is at the current root.handler
- the handler to delegate toGroovyChain
get(Handler)
,
post(Handler)
,
patch(Handler)
,
delete(Handler)
Chain patch(String path, Handler handler)
Handler
to this GroovyChain
that delegates to the given Handler
if
the relative path
matches the given path
and the request
HTTPMethod
is PATCH
.path
- the relative path to match onhandler
- the handler to delegate toGroovyChain
get(String, Handler)
,
post(String, Handler)
,
put(String, Handler)
,
delete(String, Handler)
,
handler(String, Handler)
Chain patch(Handler handler)
Handler
to this GroovyChain
that delegates to the given Handler
if
the request
HTTPMethod
is PATCH
and the path
is at the current root.handler
- the handler to delegate toGroovyChain
get(Handler)
,
post(Handler)
,
put(Handler)
,
delete(Handler)
Chain delete(String path, Handler handler)
Handler
to this GroovyChain
that delegates to the given Handler
if
the relative path
matches the given path
and the request
HTTPMethod
is DELETE
.path
- the relative path to match onhandler
- the handler to delegate toGroovyChain
get(String, Handler)
,
post(String, Handler)
,
put(String, Handler)
,
patch(String, Handler)
,
handler(String, Handler)
Chain delete(Handler handler)
Handler
to this GroovyChain
that delegates to the given Handler
if
the request
HTTPMethod
is DELETE
and the path
is at the current root.handler
- the handler to delegate toGroovyChain
get(Handler)
,
post(Handler)
,
put(Handler)
,
patch(Handler)
Chain assets(String path, String... indexFiles)
Handler
to this GroovyChain
that serves static assets at the given file system path,
relative to the contextual file system binding.
See Handlers.assets(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 directoryGroovyChain
Chain register(Object service, Handler handler)
Handler
to this GroovyChain
that inserts the given handler with the given service
addition.
The service
object will be available by its concrete type.
See Handlers.register(Object, Handler)
for more details on the Handler
created
service
- the object to add to the service for the handlershandler
- the handlers to register the service withGroovyChain
register(Class, Object, Handler)
Chain register(Object service, Action<? super Chain> action) throws Exception
Exception
<T> Chain register(Class<? super T> type, T service, Handler handler)
Handler
to this GroovyChain
that inserts the given handlers with the given service
addition.
The service
object will be available by the given type.
See Handlers.register(Class, Object, Handler)
for more details on the Handler
created
T
- the concrete type of the service additiontype
- the Type
by which to make the service object availableservice
- the object to add to the service for the handlershandler
- the handlers to register the service withGroovyChain
register(Object, Handler)
<T> Chain register(Class<? super T> type, T service, Action<? super Chain> action) throws Exception
Exception
Chain fileSystem(String path, Handler handler)
path
- the relative path
to the new file system binding pointhandler
- the definition of the handler chainGroovyChain
Chain fileSystem(String path, Action<? super Chain> action) throws Exception
Exception
Chain header(String headerName, String headerValue, Handler handler)
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.
headerName
- the name of the HTTP Header to match onheaderValue
- the value of the HTTP Header to match onhandler
- the handler to delegate to