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 |
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 . |
<T> Chain |
register(Class<? super T> type,
T service,
Action<? super Chain> action)
Adds a handler to this chain that inserts the given handler chain with the given service addition.
|
<T> Chain |
register(Class<? super T> type,
T service,
Handler handler)
Adds a handler that inserts the given handlers with the given service addition.
|
Chain |
register(Object service,
Action<? super Chain> action)
Adds a handler to this chain that inserts the given handler with the given service addition.
|
Chain |
register(Object service,
Handler handler)
Adds a handler that inserts the given handler with the given service addition.
|
@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, ratpack.registry.Registry, ratpack.func.Action)
LaunchConfig getLaunchConfig()
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 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 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)
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 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 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 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 assets(String path, String... indexFiles)
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 directoryChain register(Object service, Handler handler)
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 withregister(Class, Object, Handler)
Chain register(Object service, Action<? super Chain> action) throws Exception
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 handlersaction
- the handlers to register the service withException
- any thrown by action
register(Class, Object, Handler)
<T> Chain register(Class<? super T> type, T service, Handler handler)
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 withregister(Object, Handler)
<T> Chain register(Class<? super T> type, T service, Action<? super Chain> action) throws Exception
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 handlersaction
- the handlers which to register the service forException
- any thrown by action
register(Object, 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 header(String headerName, String headerValue, Handler handler)
headerName
- the name of the HTTP Header to match onheaderValue
- the value of the HTTP Header to match onhandler
- the handler to delegate to