In Ratpack we can use the byContent method on the Context object to send different responses based on the requested MIME type from the client. There is already support for application/json, application/xml, text/plain and text/html MIME types with corresponding methods of the ByContentSpec object that is passed as argument to the byContent method. We can match on a custom MIME type with the method type and specify the MIME type. If the type matches we can create a response.

In the following example application we have a custom renderer for a User object:

Continue reading →

When we use the render method in our Ratpack application then Ratpack will use the type of the object we want to render to find an appropriate renderer. Some renderers are built-in, like a Promise or CharSequence renderer. We can write our own renderers by implementing the ratpack.render.Renderer interface. Next we must register our renderer in the Ratpack registry.

In our example application we have a very simple User class:

Continue reading →

Ratpack has the class ratpack.handling.ReponseTimer which adds a header with the name X-Response-Time to the response. The value is the time spent in code from when the request comes in and the response is sent out. ResponseTimer is a handler we can add in our application. Alternatively we can use the static method decorator to get a handler decorator. With a handler decorator we can use the registry to add handler logic in our application.

First we use the ResponseTimer as a handler:

Continue reading →

Russel Hart has a nice example on how to extend the Ratpack Groovy DSL in the hands on ratpack project on Github. We can use the Groovy extension module feature to add new methods to arbitrary classes. If we use this to add new methods to the GroovyChain class we can use those methods in the DSL of our Groovy Ratpack application.

A Groovy extension module is just a class with a definition of the new methods we want to add to a class. The first argument of the method is the class the method is added to and the remaining arguments can be used by the implementation. We also need to create a supporting file org.codehaus.groovy.runtime.ExtensionModule with some information about our extension class. This supporting file needs to be in the classpath in the directory META-INF/services.

Continue reading →

In a previous post we have seen how to use regular expressions for path tokens. We can also name the path token for which the regular expression applies. This makes it easier to get the value in our handler code: we can just refer to the name. Also we can add a question mark to the name to make the token optional.

In the following example we use the name conferenceName for the path token with the regular expression Gr\w+:

Continue reading →

One of the strengths of Ratpack is the asynchronous execution model. An important class is the Promise class. An instance of the class will represent a value that is available later. We can invoke several operations that need be applied to a value when a Promise is activated. Usually the activation happens when we subscribe to a Promise using the then method. We can use the route method for a Promise to have a different action when a certain predicate is true. The action will stop the flow of operations, so methods that are executed after the route method are not executed anymore if the predicate is true. If the predicate is false then those methods are invoked.

The Promise class has a method onNull as a shorthand for the route method where the predicate checks if the value is null. For example we could have a service in our application that returns a Promise. If the value is null we want some special behaviour like sending a 404 status code to the client. With the following code we could achieve this:

Continue reading →

Ratpack is a lean library to build HTTP applications. Ratpack for example doesn't include functionality to validate forms that are submitted from a web page. To add form validation to our Ratpack application we must write our own implementation.

Let's write a simple application with a HTML form. We will use Hibernate Validator as a JSR 303 Bean Validation API implementation to validate the form fields. IN our application we also use the MarkupTemplateModule so we can use Groovy templates to generate HTML. We have a simple form with two fields: username and email. The username field is required and the email field needs to have a valid e-mail address. The following class uses annotations from Hibernate Validator to specify the constraints for these two fields:

Continue reading →

Ratpack 1.1 introduced a feature to use command line arguments for our application configuration. We must use the args method of the ConfigDataBuilder class. We can define a common prefix for the arguments and the separator between the configuration property and value. If we don't specify any arguments then Ratpack assumes there is no prefix and the separator is the equal sign (=).

In the following example Ratpack application we use the args method and rely on all the default settings:

Continue reading →

When we define a path in Ratpack we can use regular expressions for matching a request. We must start a token with a double colon (::) and then we can define a regular expression. Ratpack will try to match the request path and uses our regular expression.

In the following example Ratpack application we use a regular expression to match requests that start with Gr after a fixed conferences prefix:

Continue reading →

In Ratpack we can use path token as variable parts of a request. We can access a path token via the PathBinding instance that is added to the context registry by Ratpack. There is a shorthand method getPathTokens to get the PathTokens object. To get the value for a token we use the get method or with the Groovy DSL we can use square brackets with the name of the token. If we expect a token value to be of a certain type, like a Long or Boolean, we can use the asLong or asBoolean method. The value is then converted to the correct type and if the conversion fails an exception is thrown. The exception will be converted to a 500 status code in the response by the default error handler.

The PathTokens class has methods for converting to Long, Byte, Integer, Short and Boolean types with the methods asLong, asByte, asInteger, asShort and asBoolean

Continue reading →

To define endpoints in our Ratpack application we can use optional path tokens. This means that a part of the request can have a value or not, but we can a have single path definition that will match. Normally we define a variable path token with a colon (:) followed by a variable name. To make this token optional we follow it with a question mark (?). This tells Ratpack that the token can have a value or not. In our handler we now need to take into account that the path token is optional as well.

Let's write a sample Ratpack application with a path definition containing an optional token. We define a path binding for profiles/:username?. The path token username is available in our handler if the value is set, but also a request for profiles will match for this binding. Then the value for username is not set.

Continue reading →

If we use the Ratpack Gradle plugin for our project then we automatically get the Gradle application plugin. We can use this together with the Gradle Docker application plugin to deploy our Ratpack application as a Docker container very easily.

To make it work we must apply the com.bmuschko.docker-java-application in our Gradle build file. With this plugin we can define some configuration properties in the docker.javaApplication configuration block. We can set a base image instead of the default java base image. The default image tag is a made up of the project group name, application name and version. To set the exposed port number we use the port property.

Continue reading →