Monthly Archives: November 2015

Post navigation

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 (=).

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 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

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.

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.

In the Ratpack core we can find the ratpack.health.HealthCheck interface. We can implement this interface to check for example if a mail server, that we need in our application, is available. Any objects that implement this interface and are registered in the Guice registry are handled by Ratpack. Ratpack also offers a HealthCheckHandler to output the results of all health checks or a single health check identified by a name. Instead of creating a new class that implements the HealthCheck interface we can also use the HealtCheck.of method. This method accepts an argument with the name of our check and a Closure or lambda expression with the code that does the checking.

In Ratpack we can use Guice modules to organise code to provide objects to the registry. Ratpack adds configurable modules that take an extra configuration object. Values from the configuration object are used to create new objects that are provided to our application. Using the Groovy DSL we have several ways to make a configuration object available to a configurable module.

Ratpack is a lean framework. To add extra functionality, like using a database, we can use framework modules. Ratpack comes with a couple of framework modules. One of the modules is the SqlModule. This module adds a Groovy Sql instance to our application. We can use it to execute SQL code against a database. The SqlModule needs a DataSource instance, so we need to write some code to provide a DataSource instance for a PostgreSQL database.

Ratpack has very useful methods to apply application configuration in our application. We can read configuration properties from files in different formats, like JSON, YAML and Java properties, and the files can be read from different locations, like class path or file system. We can also set configuration properties via Java system properties on the command line or use environment variables.

We use the ratpack.config.ConfigData class with the static of method to add configuration properties to our application. We provide a lambda expression or Groovy closure to the of method to build our configuration. Here we specify external files, locations and other configuration options we want to include for our application. If the same configuration property is defined in multiple configuration sources Ratpack will apply the value that is last discovered. This way we can for example provide default values and allow them to be overridden with environment variables if we apply the environment variables last.

To use the values that are gathered we use the get method of the ConfigData instance. We can apply the configuration properties to the properties of a configuration class that is then automatically instantiated. We add this to the registry so we can use the configuration properties further down in our application.