Over a million developers have joined DZone.

Ratpacked: Using Optional Path Tokens

DZone's Guide to

Ratpacked: Using Optional Path Tokens

In a Ratpack app, optional path tokens let us define endpoints so that part of the request can have a value or not, but share a single path definition.

· Java Zone ·
Free Resource

The CMS developers love. Open Source, API-first and Enterprise-grade. Try BloomReach CMS for free.

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.

// File: src/ratpack/Ratpack.groovy
import static ratpack.groovy.Groovy.ratpack

ratpack {

    handlers {

        // Specify the optional path token username.
        // This path definition will match for 
        // request paths like profiles/mrhaki and
        // profiles (without slash and username value).
        path('profiles/:username?') {

            // Simply render the value of the username
            // path token if set, otherwise return "all"
            render pathTokens.getOrDefault('username', 'all')


We write the following test to check the different responses we get when we provide values for the optional token or leave out a value:

// File: src/test/groovy/com/mrhaki/ratpack/pathbinding/OptionalPathBindingSpec.groovy
package com.mrhaki.ratpack.pathbinding

import ratpack.groovy.test.GroovyRatpackMainApplicationUnderTest
import spock.lang.AutoCleanup
import spock.lang.Shared
import spock.lang.Specification
import spock.lang.Unroll

class OptionalPathBindingSpec extends Specification {

    GroovyRatpackMainApplicationUnderTest app = 
            new GroovyRatpackMainApplicationUnderTest()

    @Unroll('path #path should return "#expectedResponse"')
    def "check response for request with and without optional token"() {
        def response = app.httpClient.get(path)

        response.body.text == expectedResponse

        path                  || expectedResponse
        '/profiles/mrhaki'    || 'mrhaki'
        '/profiles/hubert'    || 'hubert'
        '/profiles'           || 'all'
        '/profiles/'          || ''
        '/profiles/mrhaki/42' || 'Client error 404'


BloomReach CMS: the API-first CMS of the future. Open-source & enterprise-grade. - As a Java developer, you will feel at home using Maven builds and your favorite IDE (e.g. Eclipse or IntelliJ) and continuous integration server (e.g. Jenkins). Manage your Java objects using Spring Framework, write your templates in JSP or Freemarker. Try for free.

ratpack ,groovy

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}