Package ratpack.groovy.handling

Interface GroovyChain

All Superinterfaces:

Chain

All Known Implementing Classes:

GroovyChainAction

public interface GroovyChain
extends Chain

A Groovy oriented handler chain builder DSL.

The methods specific to this subclass create Handler instances from closures and add them to the underlying chain.

These methods are generally shortcuts for all(Handler) on this underlying chain.

Method Summary

Modifier and Type	Method	Description
default GroovyChain	all(Closure<?> handler)	Adds the given Closure as a Handler to this GroovyChain.
default GroovyChain	all(Class<? extends Handler> handler)
GroovyChain	all(Handler handler)	Adds the given handler to this.
default Handler	chain(Closure<?> closure)	Creates a handler from the given closure.
default GroovyChain	delete(Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is DELETE and the path is at the current root.
default GroovyChain	delete(Class<? extends Handler> handler)
default GroovyChain	delete(String path, Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is DELETE.
default GroovyChain	delete(String path, Class<? extends Handler> handler)
default GroovyChain	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.
default GroovyChain	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.
default GroovyChain	files()	Chain.files(Action), using the default config.
default GroovyChain	files(Closure<?> closure)
default GroovyChain	files(Action<? super FileHandlerSpec> config)	Adds a handler that serves files from the file system.
default GroovyChain	fileSystem(String path, Closure<?> handlers)	Creates a List of Handler from the given Closure and adds a Handler to this GroovyChain that changes the FileSystemBinding for the Handler list.
default GroovyChain	fileSystem(String path, Class<? extends Action<? super Chain>> action)
default GroovyChain	fileSystem(String path, Action<? super Chain> action)	Adds a handler to this chain that changes the FileSystemBinding for the given handler chain.
static GroovyChain	from(Chain chain)	Creates a Groovy chain wrapper over a chain instance.
default GroovyChain	get(Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is GET and the path is at the current root.
default GroovyChain	get(Class<? extends Handler> handler)
default GroovyChain	get(String path, Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is GET.
default GroovyChain	get(String path, Class<? extends Handler> handler)
default GroovyChain	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.
default GroovyChain	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.
default GroovyChain	host(String hostName, Closure<?> handler)	If the request has a Host header that matches the given host name exactly, handling will be delegated to the chain defined by the given closure.
default GroovyChain	host(String hostName, Class<? extends Action<? super Chain>> action)
default GroovyChain	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.
default GroovyChain	insert(Closure<?> closure)	Inserts the given nested handler chain.
default GroovyChain	insert(Class<? extends Action<? super Chain>> action)
default GroovyChain	insert(Action<? super Chain> action)	Inserts the given nested handler chain.
default GroovyChain	notFound()	Raises a 404 Context.clientError(int).
default GroovyChain	onlyIf(Closure<?> test, Closure<?> handler)
default GroovyChain	onlyIf(Closure<?> test, Class<? extends Handler> handler)
default GroovyChain	onlyIf(Closure<?> test, Handler handler)
default GroovyChain	onlyIf(Predicate<? super Context> test, Closure<?> handler)
default GroovyChain	onlyIf(Predicate<? super Context> test, Class<? extends Handler> handler)
default GroovyChain	onlyIf(Predicate<? super Context> test, Handler handler)	Invokes the given handler only if the predicate passes.
default GroovyChain	options(Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is OPTIONS and the path is at the current root.
default GroovyChain	options(Class<? extends Handler> handler)
default GroovyChain	options(String path, Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is OPTIONS.
default GroovyChain	options(String path, Class<? extends Handler> handler)
default GroovyChain	options(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 OPTIONS.
default GroovyChain	options(Handler handler)	Adds a handler that delegates to the given handler if the request HTTPMethod is OPTIONS and the path is at the current root.
default GroovyChain	patch(Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is PATCH and the path is at the current root.
default GroovyChain	patch(Class<? extends Handler> handler)
default GroovyChain	patch(String path, Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is PATCH.
default GroovyChain	patch(String path, Class<? extends Handler> handler)
default GroovyChain	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.
default GroovyChain	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.
default GroovyChain	path(Closure<?> handler)
default GroovyChain	path(Class<? extends Handler> handler)
default GroovyChain	path(String path, Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path exactly.
default GroovyChain	path(String path, Class<? extends Handler> handler)
default GroovyChain	path(String path, Handler handler)	Adds a handler that delegates to the given handler if the relative path matches the given path exactly.
default GroovyChain	path(Handler handler)
default GroovyChain	post(Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is POST and the path is at the current root.
default GroovyChain	post(Class<? extends Handler> handler)
default GroovyChain	post(String path, Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is POST.
default GroovyChain	post(String path, Class<? extends Handler> handler)
default GroovyChain	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.
default GroovyChain	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.
default GroovyChain	prefix(String prefix, Closure<?> chain)	Creates a List of Handler from the given Closure and adds a Handler to this GroovyChain that delegates to the Handler list if the relative path starts with the given prefix.
default GroovyChain	prefix(String prefix, Class<? extends Action<? super Chain>> action)
default GroovyChain	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.
default GroovyChain	put(Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is PUT and the path is at the current root.
default GroovyChain	put(Class<? extends Handler> handler)
default GroovyChain	put(String path, Closure<?> handler)	Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is PUT.
default GroovyChain	put(String path, Class<? extends Handler> handler)
default GroovyChain	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.
default GroovyChain	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.
default GroovyChain	redirect(int code, String location)	Sends an HTTP redirect to the specified location.
default GroovyChain	register(Closure<?> closure)
default GroovyChain	register(Registry registry)	Makes the contents of the given registry available for downstream handlers of the same nesting level.
default GroovyChain	register(Registry registry, Closure<?> handlers)
default GroovyChain	register(Registry registry, Class<? extends Action<? super Chain>> action)
default GroovyChain	register(Registry registry, Action<? super Chain> action)	Adds a handler that inserts the given handler chain with the given registry via Context.insert(Registry, Handler...).
default GroovyChain	register(Action<? super RegistrySpec> action)	Builds a new registry via the given action, then registers it via Chain.register(Registry).
default GroovyChain	register(Action<? super RegistrySpec> registryAction, Closure<?> handler)
default GroovyChain	register(Action<? super RegistrySpec> registryAction, Class<? extends Action<? super Chain>> action)
default GroovyChain	register(Action<? super RegistrySpec> registryAction, Action<? super Chain> chainAction)	Adds a handler that inserts the given handler chain with a registry built by the given action via Context.insert(Registry, Handler...).
default GroovyChain	when(boolean test, Closure<?> handlers)	Inlines the given handlers if test is true.
default GroovyChain	when(boolean test, Closure<?> ifHandlers, Closure<?> elseHandlers)	Inlines the appropriate handlers based on the given test.
default GroovyChain	when(boolean test, Class<? extends Action<? super Chain>> action)	Inlines the given chain if test is true.
default GroovyChain	when(boolean test, Class<? extends Action<? super Chain>> onTrue, Class<? extends Action<? super Chain>> onFalse)	Inlines the appropriate chain based on the given test.
default GroovyChain	when(boolean test, Action<? super Chain> action)	Inlines the given chain if test is true.
default GroovyChain	when(boolean test, Action<? super Chain> onTrue, Action<? super Chain> onFalse)	Inlines the appropriate chain based on the given test.
default GroovyChain	when(Closure<?> test, Closure<?> handlers)
default GroovyChain	when(Closure<?> test, Closure<?> ifHandlers, Closure<?> elseHandlers)
default GroovyChain	when(Closure<?> test, Class<? extends Action<? super Chain>> action)
default GroovyChain	when(Closure<?> test, Class<? extends Action<? super Chain>> ifAction, Class<? extends Action<? super Chain>> elseAction)
default GroovyChain	when(Closure<?> test, Action<? super Chain> chain)
default GroovyChain	when(Closure<?> test, Action<? super Chain> ifChain, Action<? super Chain> elseChain)
default GroovyChain	when(Predicate<? super Context> test, Closure<?> handlers)
default GroovyChain	when(Predicate<? super Context> test, Closure<?> ifHandlers, Closure<?> elseHandlers)
default GroovyChain	when(Predicate<? super Context> test, Class<? extends Action<? super Chain>> action)
default GroovyChain	when(Predicate<? super Context> test, Class<? extends Action<? super Chain>> onTrue, Class<? extends Action<? super Chain>> onFalse)
default GroovyChain	when(Predicate<? super Context> test, Action<? super Chain> action)
default GroovyChain	when(Predicate<? super Context> test, Action<? super Chain> onTrue, Action<? super Chain> onFalse)

Methods inherited from interface ratpack.core.handling.Chain

chain, chain, getRegistry, getServerConfig

Method Detail

from

static GroovyChain from(Chain chain)

Creates a Groovy chain wrapper over a chain instance.

Parameters:

chain - a chain instance

Returns:

a Groovy wrapper

all

default GroovyChain all(@DelegatesTo(value=GroovyContext.class,strategy=1)
                        Closure<?> handler)

Adds the given Closure as a Handler to this GroovyChain.

Parameters:

handler - the Closure to add

Returns:

this GroovyChain

all

GroovyChain all(Handler handler)

Adds the given handler to this.

Specified by:

all in interface Chain

Parameters:

handler - the handler to add

Returns:

this

all

default GroovyChain all(Class<? extends Handler> handler)

Specified by:

all in interface Chain

chain

default Handler chain(@DelegatesTo(value=GroovyChain.class,strategy=1)
                      Closure<?> closure)
               throws Exception

Creates a handler from the given closure.

Parameters:

closure - a chain definition

Returns:

a new handler

Throws:

Exception - any thrown by closure

delete

default GroovyChain delete(String path,
                           @DelegatesTo(value=GroovyContext.class,strategy=1)
                           Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is DELETE.

See delete(String, Handler) for more details.

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this GroovyChain

delete

default GroovyChain delete(@DelegatesTo(value=GroovyContext.class,strategy=1)
                           Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is DELETE and the path is at the current root.

See delete(Handler) for more details.

Parameters:

handler - the handler to delegate to

Returns:

this GroovyChain

delete

default GroovyChain 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.

Specified by:

delete in interface Chain

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this

See Also:

Chain.get(String, Handler), Chain.post(String, Handler), Chain.put(String, Handler), Chain.patch(String, Handler), Chain.path(String, Handler)

delete

default GroovyChain delete(String path,
                           Class<? extends Handler> handler)

Specified by:

delete in interface Chain

delete

default GroovyChain 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.

Specified by:

delete in interface Chain

Parameters:

handler - the handler to delegate to

Returns:

this

See Also:

Chain.get(Handler), Chain.post(Handler), Chain.put(Handler), Chain.patch(Handler)

delete

default GroovyChain delete(Class<? extends Handler> handler)

Specified by:

delete in interface Chain

fileSystem

default GroovyChain fileSystem(String path,
                               @DelegatesTo(value=GroovyChain.class,strategy=1)
                               Closure<?> handlers)
                        throws Exception

Creates a List of Handler from the given Closure and adds a Handler to this GroovyChain that changes the FileSystemBinding for the Handler list.

See fileSystem(String, Action) for more details.

Parameters:

path - the relative path to the new file system binding point

handlers - the definition of the handler chain

Returns:

this GroovyChain

Throws:

Exception - any thrown by closure

fileSystem

default GroovyChain fileSystem(String path,
                               Action<? super Chain> action)
                        throws Exception

Adds a handler to this chain that changes the FileSystemBinding for the given handler chain.

Specified by:

fileSystem in interface Chain

Parameters:

path - the relative path to the new file system binding point

action - the definition of the all chain

Returns:

this

Throws:

Exception - any thrown by action

fileSystem

default GroovyChain fileSystem(String path,
                               Class<? extends Action<? super Chain>> action)
                        throws Exception

Specified by:

fileSystem in interface Chain

Throws:

Exception

files

default GroovyChain files(Action<? super FileHandlerSpec> config)
                   throws Exception

Adds a handler that serves files from the file system.

The given action configures how and what files will be served. The handler binds to a request path and a directory within the current filesystem binding. The portion of the request path past the path binding identifies the target file within the directory.

 import ratpack.test.embed.EphemeralBaseDir;
 import ratpack.test.embed.EmbeddedApp;

 import static org.junit.jupiter.api.Assertions.assertEquals;

 public class Example {
   public static void main(String... args) throws Exception {
     EphemeralBaseDir.tmpDir().use(baseDir -> {
       baseDir.write("public/some.text", "foo");
       baseDir.write("public/index.html", "bar");
       EmbeddedApp.of(s -> s
         .serverConfig(c -> c.baseDir(baseDir.getRoot()))
         .handlers(c -> c
           .files(f -> f.dir("public").indexFiles("index.html"))
         )
       ).test(httpClient -> {
         assertEquals("foo", httpClient.getText("some.text"));
         assertEquals("bar", httpClient.getText());
         assertEquals(404, httpClient.get("no-file-here").getStatusCode());
       });
     });
   }
 }
 

Specified by:

files in interface Chain

Parameters:

config - the file handler configuration

Returns:

this

Throws:

Exception - any thrown by config

See Also:

Handlers.files(ServerConfig, Action), FileHandlerSpec

files

default GroovyChain files()

Description copied from interface: Chain

Chain.files(Action), using the default config.

Specified by:

files in interface Chain

Returns:

this

files

default GroovyChain files(@DelegatesTo(value=FileHandlerSpec.class,strategy=1)
                          Closure<?> closure)
                   throws Exception

Throws:

Exception

get

default GroovyChain 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.

Specified by:

get in interface Chain

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this

See Also:

Chain.post(String, Handler), Chain.put(String, Handler), Chain.patch(String, Handler), Chain.delete(String, Handler), Chain.path(String, Handler)

get

default GroovyChain get(String path,
                        Class<? extends Handler> handler)

Specified by:

get in interface Chain

get

default GroovyChain 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.

Specified by:

get in interface Chain

Parameters:

handler - the handler to delegate to

Returns:

this

See Also:

Chain.post(Handler), Chain.put(Handler), Chain.patch(Handler), Chain.delete(Handler)

get

default GroovyChain get(Class<? extends Handler> handler)

Specified by:

get in interface Chain

get

default GroovyChain get(String path,
                        @DelegatesTo(value=GroovyContext.class,strategy=1)
                        Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is GET.

See get(String, Handler) for more details.

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this GroovyChain

get

default GroovyChain get(@DelegatesTo(value=GroovyContext.class,strategy=1)
                        Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is GET and the path is at the current root.

See get(Handler) for more details.

Parameters:

handler - the handler to delegate to

Returns:

this GroovyChain

host

default GroovyChain host(String hostName,
                         Action<? super Chain> action)
                  throws Exception

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.
    host("foo.com", new Action<Chain>() {
      public void execute(Chain hostChain) {
        hostChain.all(new Handler() {
          public void handle(Context context) {
            context.getResponse().send("Host Handler");
          }
        });
      }
    });
 

Specified by:

host in interface Chain

Parameters:

hostName - the name of the HTTP Header to match on

action - the handler chain to delegate to if the host matches

Returns:

this

Throws:

Exception - any thrown by action

host

default GroovyChain host(String hostName,
                         Class<? extends Action<? super Chain>> action)
                  throws Exception

Specified by:

host in interface Chain

Throws:

Exception

host

default GroovyChain host(String hostName,
                         @DelegatesTo(value=GroovyChain.class,strategy=1)
                         Closure<?> handler)
                  throws Exception

If the request has a Host header that matches the given host name exactly, handling will be delegated to the chain defined by the given closure.

Parameters:

hostName - the name of the HTTP Header to match on

handler - the handler to delegate to

Returns:

this GroovyChain

Throws:

Exception - any thrown by closure

See Also:

host(String, Action)

insert

default GroovyChain insert(Action<? super Chain> action)
                    throws Exception

Inserts the given nested handler chain.

Shorter form of Chain.all(Handler) handler}(chain(action).

Specified by:

insert in interface Chain

Parameters:

action - the handler chain to insert

Returns:

this

Throws:

Exception - any thrown by action

insert

default GroovyChain insert(Class<? extends Action<? super Chain>> action)
                    throws Exception

Specified by:

insert in interface Chain

Throws:

Exception

insert

default GroovyChain insert(@DelegatesTo(value=GroovyChain.class,strategy=1)
                           Closure<?> closure)
                    throws Exception

Inserts the given nested handler chain.

Shorter form of all(Handler) handler}(chain(closure).

Parameters:

closure - the handler chain to insert

Returns:

this

Throws:

Exception - any thrown by closure

patch

default GroovyChain 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.

Specified by:

patch in interface Chain

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this

See Also:

Chain.get(String, Handler), Chain.post(String, Handler), Chain.put(String, Handler), Chain.delete(String, Handler), Chain.path(String, Handler)

patch

default GroovyChain patch(String path,
                          Class<? extends Handler> handler)

Specified by:

patch in interface Chain

patch

default GroovyChain 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.

Specified by:

patch in interface Chain

Parameters:

handler - the handler to delegate to

Returns:

this

See Also:

Chain.get(Handler), Chain.post(Handler), Chain.put(Handler), Chain.delete(Handler)

patch

default GroovyChain patch(Class<? extends Handler> handler)

Specified by:

patch in interface Chain

patch

default GroovyChain patch(String path,
                          @DelegatesTo(value=GroovyContext.class,strategy=1)
                          Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is PATCH.

See put(String, Handler) for more details.

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this GroovyChain

patch

default GroovyChain patch(@DelegatesTo(value=GroovyContext.class,strategy=1)
                          Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is PATCH and the path is at the current root.

See put(Handler) for more details.

Parameters:

handler - the handler to delegate to

Returns:

this GroovyChain

options

default GroovyChain options(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 OPTIONS.

Specified by:

options in interface Chain

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this

See Also:

Chain.get(String, Handler), Chain.post(String, Handler), Chain.put(String, Handler), Chain.delete(String, Handler), Chain.path(String, Handler)

options

default GroovyChain options(String path,
                            Class<? extends Handler> handler)

Specified by:

options in interface Chain

Parameters:

path - the path to bind to

handler - a handler

Returns:

this

options

default GroovyChain options(Handler handler)

Adds a handler that delegates to the given handler if the request HTTPMethod is OPTIONS and the path is at the current root.

Specified by:

options in interface Chain

Parameters:

handler - the handler to delegate to

Returns:

this

See Also:

Chain.get(Handler), Chain.post(Handler), Chain.put(Handler), Chain.delete(Handler)

options

default GroovyChain options(Class<? extends Handler> handler)

Specified by:

options in interface Chain

Parameters:

handler - a handler

Returns:

{code this}

options

default GroovyChain options(String path,
                            @DelegatesTo(value=GroovyContext.class,strategy=1)
                            Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is OPTIONS.

See put(String, Handler) for more details.

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this GroovyChain

Since:

1.1

options

default GroovyChain options(@DelegatesTo(value=GroovyContext.class,strategy=1)
                            Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is OPTIONS and the path is at the current root.

See put(Handler) for more details.

Parameters:

handler - the handler to delegate to

Returns:

this GroovyChain

Since:

1.1

path

default GroovyChain path(String path,
                         Handler handler)

Adds a handler 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 Chain.prefix(String, Action) 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 all 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.

Specified by:

path in interface Chain

Parameters:

path - the relative path to match exactly on

handler - the handler to delegate to

Returns:

this

See Also:

Chain.post(String, Handler), Chain.get(String, Handler), Chain.put(String, Handler), Chain.patch(String, Handler), Chain.delete(String, Handler)

path

default GroovyChain path(Handler handler)

Specified by:

path in interface Chain

path

default GroovyChain path(String path,
                         Class<? extends Handler> handler)

Specified by:

path in interface Chain

path

default GroovyChain path(Class<? extends Handler> handler)

Specified by:

path in interface Chain

path

default GroovyChain path(String path,
                         @DelegatesTo(value=GroovyContext.class,strategy=1)
                         Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path exactly.

See path(String, Handler) for more details.

Parameters:

path - the relative path to match exactly on

handler - the handler to delegate to

Returns:

this GroovyChain

path

default GroovyChain path(@DelegatesTo(value=GroovyContext.class,strategy=1)
                         Closure<?> handler)

post

default GroovyChain 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.

Specified by:

post in interface Chain

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this

See Also:

Chain.get(String, Handler), Chain.put(String, Handler), Chain.patch(String, Handler), Chain.delete(String, Handler), Chain.path(String, Handler)

post

default GroovyChain post(String path,
                         Class<? extends Handler> handler)

Specified by:

post in interface Chain

post

default GroovyChain 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.

Specified by:

post in interface Chain

Parameters:

handler - the handler to delegate to

Returns:

this

See Also:

Chain.get(Handler), Chain.put(Handler), Chain.patch(Handler), Chain.delete(Handler)

post

default GroovyChain post(Class<? extends Handler> handler)

Specified by:

post in interface Chain

post

default GroovyChain post(String path,
                         @DelegatesTo(value=GroovyContext.class,strategy=1)
                         Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is POST.

See post(String, Handler) for more details.

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this GroovyChain

post

default GroovyChain post(@DelegatesTo(value=GroovyContext.class,strategy=1)
                         Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is POST and the path is at the current root.

See post(Handler) for more details.

Parameters:

handler - the handler to delegate to

Returns:

this GroovyChain

prefix

default GroovyChain prefix(String prefix,
                           Action<? super Chain> action)
                    throws Exception

Adds a handler 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", new Action<Chain>() {
       public void execute(Chain personChain) throws Exception {
         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.

Specified by:

prefix in interface Chain

Parameters:

prefix - the relative path to match on

action - the handler chain to delegate to if the prefix matches

Returns:

this

Throws:

Exception - any thrown by action

prefix

default GroovyChain prefix(String prefix,
                           Class<? extends Action<? super Chain>> action)
                    throws Exception

Specified by:

prefix in interface Chain

Throws:

Exception

prefix

default GroovyChain prefix(String prefix,
                           @DelegatesTo(value=GroovyChain.class,strategy=1)
                           Closure<?> chain)
                    throws Exception

Creates a List of Handler from the given Closure and adds a Handler to this GroovyChain that delegates to the Handler list if the relative path starts with the given prefix.

See Chain.prefix(String, Action) for more details.

Parameters:

prefix - the relative path to match on

chain - the definition of the chain to delegate to

Returns:

this GroovyChain

Throws:

Exception - any exception thrown by the given closure

put

default GroovyChain 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.

Specified by:

put in interface Chain

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this

See Also:

Chain.get(String, Handler), Chain.post(String, Handler), Chain.patch(String, Handler), Chain.delete(String, Handler), Chain.path(String, Handler)

put

default GroovyChain put(String path,
                        Class<? extends Handler> handler)

Specified by:

put in interface Chain

put

default GroovyChain 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.

Specified by:

put in interface Chain

Parameters:

handler - the handler to delegate to

Returns:

this

See Also:

Chain.get(Handler), Chain.post(Handler), Chain.patch(Handler), Chain.delete(Handler)

put

default GroovyChain put(Class<? extends Handler> handler)

Specified by:

put in interface Chain

put

default GroovyChain put(String path,
                        @DelegatesTo(value=GroovyContext.class,strategy=1)
                        Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the relative path matches the given path and the request HTTPMethod is PUT.

See put(String, Handler) for more details.

Parameters:

path - the relative path to match on

handler - the handler to delegate to

Returns:

this GroovyChain

put

default GroovyChain put(@DelegatesTo(value=GroovyContext.class,strategy=1)
                        Closure<?> handler)

Adds a Handler to this GroovyChain that delegates to the given Closure as a Handler if the request HTTPMethod is PUT and the path is at the current root.

See put(Handler) for more details.

Parameters:

handler - the handler to delegate to

Returns:

this GroovyChain

redirect

default GroovyChain redirect(int code,
                             String location)

Sends an HTTP redirect to the specified location.

The handler to add is created via Handlers.redirect(int, String).

Specified by:

redirect in interface Chain

Parameters:

code - the 3XX HTTP status code.

location - the URL to set in the Location response header

Returns:

this

See Also:

Handlers.redirect(int, String)

register

default GroovyChain register(Registry registry)

Makes the contents of the given registry available for downstream handlers of the same nesting level.

The registry is inserted via the Context.next(Registry) method.

Specified by:

register in interface Chain

Parameters:

registry - the registry whose contents should be made available to downstream handlers

Returns:

this

register

default GroovyChain register(Action<? super RegistrySpec> action)
                      throws Exception

Builds a new registry via the given action, then registers it via Chain.register(Registry).

Specified by:

register in interface Chain

Parameters:

action - the definition of a registry

Returns:

this

Throws:

Exception - any thrown by action

register

default GroovyChain register(Registry registry,
                             Action<? super Chain> action)
                      throws Exception

Adds a handler that inserts the given handler chain with the given registry via Context.insert(Registry, Handler...).

Specified by:

register in interface Chain

Parameters:

registry - the registry to insert

action - the definition of the handler chain

Returns:

this

Throws:

Exception - any thrown by action

register

default GroovyChain register(Registry registry,
                             Class<? extends Action<? super Chain>> action)
                      throws Exception

Specified by:

register in interface Chain

Throws:

Exception

register

default GroovyChain register(Action<? super RegistrySpec> registryAction,
                             Action<? super Chain> chainAction)
                      throws Exception

Adds a handler that inserts the given handler chain with a registry built by the given action via Context.insert(Registry, Handler...).

Specified by:

register in interface Chain

Parameters:

registryAction - the definition of the registry to insert]

chainAction - the definition of the handler chain

Returns:

this

Throws:

Exception - any thrown by action

register

default GroovyChain register(Action<? super RegistrySpec> registryAction,
                             Class<? extends Action<? super Chain>> action)
                      throws Exception

Specified by:

register in interface Chain

Throws:

Exception

register

default GroovyChain register(Action<? super RegistrySpec> registryAction,
                             @DelegatesTo(value=GroovyChain.class,strategy=1)
                             Closure<?> handler)
                      throws Exception

Throws:

Exception

register

default GroovyChain register(Registry registry,
                             @DelegatesTo(value=GroovyChain.class,strategy=1)
                             Closure<?> handlers)
                      throws Exception

Throws:

Exception

register

default GroovyChain register(@DelegatesTo(value=RegistrySpec.class,strategy=1)
                             Closure<?> closure)
                      throws Exception

Throws:

Exception

when

default GroovyChain when(Predicate<? super Context> test,
                         Action<? super Chain> action)
                  throws Exception

Specified by:

when in interface Chain

Throws:

Exception

when

default GroovyChain when(Predicate<? super Context> test,
                         Class<? extends Action<? super Chain>> action)
                  throws Exception

Specified by:

when in interface Chain

Throws:

Exception

when

default GroovyChain when(Predicate<? super Context> test,
                         @DelegatesTo(value=GroovyChain.class,strategy=1)
                         Closure<?> handlers)
                  throws Exception

Throws:

Exception

when

default GroovyChain when(@DelegatesTo(value=GroovyContext.class,strategy=1)
                         Closure<?> test,
                         @DelegatesTo(value=GroovyChain.class,strategy=1)
                         Closure<?> handlers)
                  throws Exception

Throws:

Exception

when

default GroovyChain when(@DelegatesTo(value=GroovyContext.class,strategy=1)
                         Closure<?> test,
                         Action<? super Chain> chain)
                  throws Exception

Throws:

Exception

when

default GroovyChain when(@DelegatesTo(value=GroovyContext.class,strategy=1)
                         Closure<?> test,
                         Class<? extends Action<? super Chain>> action)
                  throws Exception

Throws:

Exception

when

default GroovyChain when(boolean test,
                         @DelegatesTo(value=GroovyChain.class,strategy=1)
                         Closure<?> handlers)
                  throws Exception

Inlines the given handlers if test is true.

This is literally just sugar for wrapping the given action in an if statement. It can be useful when conditionally adding handlers based on state available when building the chain.

Parameters:

test - whether to include the given chain action

handlers - the handlers to maybe include

Returns:

this

Throws:

Exception - any thrown by action

Since:

1.4

See Also:

Chain.when(boolean, Action)

when

default GroovyChain when(boolean test,
                         Action<? super Chain> action)
                  throws Exception

Inlines the given chain if test is true.

This is literally just sugar for wrapping the given action in an if statement. It can be useful when conditionally adding handlers based on state available when building the chain.

 import ratpack.test.embed.EmbeddedApp;

 import static org.junit.jupiter.api.Assertions.assertEquals;

 public class Example {

   public static void main(String... args) throws Exception {
     EmbeddedApp.of(a -> a
       .registryOf(r -> r.add(1))
       .handlers(c -> c
         .when(c.getRegistry().get(Integer.class) == 0, i -> i
           .get(ctx -> ctx.render("ok"))
         )
       )
     ).test(httpClient ->
       assertEquals(httpClient.get().getStatusCode(), 404)
     );

     EmbeddedApp.of(a -> a
       .registryOf(r -> r.add(0))
       .handlers(c -> c
         .when(c.getRegistry().get(Integer.class) == 0, i -> i
           .get(ctx -> ctx.render("ok"))
         )
       )
     ).test(httpClient ->
       assertEquals(httpClient.getText(), "ok")
     );
   }
 }
 

Specified by:

when in interface Chain

Parameters:

test - whether to include the given chain action

action - the chain action to maybe include

Returns:

this

Throws:

Exception - any thrown by action

when

default GroovyChain when(boolean test,
                         Class<? extends Action<? super Chain>> action)
                  throws Exception

Inlines the given chain if test is true.

Similar to Chain.when(boolean, Action), except obtains the action instance from the registry by the given type.

Specified by:

when in interface Chain

Parameters:

test - whether to include the given chain action

action - the chain action to maybe include

Returns:

this

Throws:

Exception - any thrown by action

when

default GroovyChain when(Predicate<? super Context> test,
                         Action<? super Chain> onTrue,
                         Action<? super Chain> onFalse)
                  throws Exception

Specified by:

when in interface Chain

Throws:

Exception

when

default GroovyChain when(Predicate<? super Context> test,
                         Class<? extends Action<? super Chain>> onTrue,
                         Class<? extends Action<? super Chain>> onFalse)
                  throws Exception

Specified by:

when in interface Chain

Throws:

Exception

when

default GroovyChain when(Predicate<? super Context> test,
                         @DelegatesTo(value=GroovyChain.class,strategy=1)
                         Closure<?> ifHandlers,
                         @DelegatesTo(value=GroovyChain.class,strategy=1)
                         Closure<?> elseHandlers)
                  throws Exception

Throws:

Exception

when

default GroovyChain when(@DelegatesTo(value=GroovyContext.class,strategy=1)
                         Closure<?> test,
                         @DelegatesTo(value=GroovyChain.class,strategy=1)
                         Closure<?> ifHandlers,
                         @DelegatesTo(value=GroovyChain.class,strategy=1)
                         Closure<?> elseHandlers)
                  throws Exception

Throws:

Exception

when

default GroovyChain when(@DelegatesTo(value=GroovyContext.class,strategy=1)
                         Closure<?> test,
                         Action<? super Chain> ifChain,
                         Action<? super Chain> elseChain)
                  throws Exception

Throws:

Exception

when

default GroovyChain when(@DelegatesTo(value=GroovyContext.class,strategy=1)
                         Closure<?> test,
                         Class<? extends Action<? super Chain>> ifAction,
                         Class<? extends Action<? super Chain>> elseAction)
                  throws Exception

Throws:

Exception

when

default GroovyChain when(boolean test,
                         @DelegatesTo(value=GroovyChain.class,strategy=1)
                         Closure<?> ifHandlers,
                         @DelegatesTo(value=GroovyChain.class,strategy=1)
                         Closure<?> elseHandlers)
                  throws Exception

Inlines the appropriate handlers based on the given test.

A value of true will result in the given ifHandlers being used. A value of false will result in the given elseHandlers being used.

This is literally just sugar for wrapping the given action in an if/else statement. It can be useful when conditionally adding handlers based on state available when building the chain.

Parameters:

test - predicate to decide which handlers to include

ifHandlers - the handlers to include when the test is true

elseHandlers - the handlers to include when the test is false

Returns:

this

Throws:

Exception - any thrown by action

Since:

1.5

See Also:

Chain.when(boolean, Action, Action)

when

default GroovyChain when(boolean test,
                         Action<? super Chain> onTrue,
                         Action<? super Chain> onFalse)
                  throws Exception

Inlines the appropriate chain based on the given test.

This is literally just sugar for wrapping the given action in an if/else statement. It can be useful when conditionally adding handlers based on state available when building the chain.

 import ratpack.test.embed.EmbeddedApp;

 import static org.junit.jupiter.api.Assertions.assertEquals;

 public class Example {

   public static void main(String... args) throws Exception {
     EmbeddedApp.of(a -> a
       .registryOf(r -> r.add(1))
       .handlers(c -> c
         .when(c.getRegistry().get(Integer.class) == 0,
            i -> i.get(ctx -> ctx.render("ok")),
            i -> i.get(ctx -> ctx.render("ko"))
         )
       )
     ).test(httpClient ->
       assertEquals(httpClient.getText(), "ko")
     );

     EmbeddedApp.of(a -> a
       .registryOf(r -> r.add(0))
       .handlers(c -> c
         .when(c.getRegistry().get(Integer.class) == 0,
            i -> i.get(ctx -> ctx.render("ok")),
            i -> i.get(ctx -> ctx.render("ko"))
         )
       )
     ).test(httpClient ->
       assertEquals(httpClient.getText(), "ok")
     );
   }
 }
 

Specified by:

when in interface Chain

Parameters:

test - predicate to decide which action include

onTrue - the chain action to include when the predicate is true

onFalse - the chain action to include when the predicate is false

Returns:

this

Throws:

Exception - any thrown by action

when

default GroovyChain when(boolean test,
                         Class<? extends Action<? super Chain>> onTrue,
                         Class<? extends Action<? super Chain>> onFalse)
                  throws Exception

Inlines the appropriate chain based on the given test.

Similar to Chain.when(boolean, Action, Action), except obtains the action instance from the registry by the given type.

Specified by:

when in interface Chain

Parameters:

test - predicate to decide which action to include

onTrue - the chain action to include when the predicate is true

onFalse - the chain action to include when the predicate is false

Returns:

this

Throws:

Exception - any thrown by action

onlyIf

default GroovyChain onlyIf(Predicate<? super Context> test,
                           Handler handler)

Invokes the given handler only if the predicate passes.

This method differs from when() in that it does not insert the handler; but directly calls its Handler.handle(Context) method.

Specified by:

onlyIf in interface Chain

Parameters:

test - the predicate

handler - the handler

Returns:

this

onlyIf

default GroovyChain onlyIf(Predicate<? super Context> test,
                           Class<? extends Handler> handler)

Specified by:

onlyIf in interface Chain

onlyIf

default GroovyChain onlyIf(Predicate<? super Context> test,
                           @DelegatesTo(value=GroovyContext.class,strategy=1)
                           Closure<?> handler)

onlyIf

default GroovyChain onlyIf(@DelegatesTo(value=GroovyContext.class,strategy=1)
                           Closure<?> test,
                           @DelegatesTo(value=GroovyContext.class,strategy=1)
                           Closure<?> handler)

onlyIf

default GroovyChain onlyIf(@DelegatesTo(value=GroovyContext.class,strategy=1)
                           Closure<?> test,
                           Handler handler)

onlyIf

default GroovyChain onlyIf(@DelegatesTo(value=GroovyContext.class,strategy=1)
                           Closure<?> test,
                           Class<? extends Handler> handler)

notFound

default GroovyChain notFound()

Raises a 404 Context.clientError(int).

This can be used to effectively terminate processing early. This is sometimes useful when using a scoped client error handler.

 import ratpack.core.error.ClientErrorHandler;
 import ratpack.test.embed.EmbeddedApp;

 import static org.junit.jupiter.api.Assertions.assertEquals;

 public class Example {
   public static void main(String... args) throws Exception {
     EmbeddedApp.of(s -> s
         .registryOf(r -> r
             .add(ClientErrorHandler.class, (ctx, code) -> ctx.render("global"))
         )
         .handlers(c -> c
             .prefix("api", api -> api
                 .register(r -> r.add(ClientErrorHandler.class, (ctx, code) -> ctx.render("scoped")))
                 .get("foo", ctx -> ctx.render("foo"))
                 .notFound()
             )
         )
     ).test(http -> {
       assertEquals(http.getText("not-there"), "global");
       assertEquals(http.getText("api/foo"), "foo");
       assertEquals(http.getText("api/not-there"), "scoped");
     });
   }
 }
 

Specified by:

notFound in interface Chain

Returns:

this