This manual is a work in progress and is currently incomplete.
If you'd like to help improve it, and we hope you do, please see the README.

12 Google Guice integration

The ratpack-guice jar provides integration with Google Guice for modularisation and dependency injection. It is typically used in most Ratpack applications, but it is not a mandatory dependency. However, the ratpack-groovy jar does depend on the Guice integration.

See the Guice package API documentation for detailed usage information.

12.1 Modules

Guice provides the concept of a module, which is a kind of recipe for providing objects. See Guice’s “Getting Started” documentation for details.

The ratpack-guice library provides the BindingsSpec type for specifying the bindings for the application.

12.2 Dependency injected handlers

The Guice integration gives you a means of decoupling the components of your application. You can factor out functionality into standalone (i.e. non Handler) objects and use these objects from your handlers. This makes your code more maintainable and more testable. This is the standard “Dependency Injection” or “Inversion of Control” pattern.

The Guice class provides static handler() factory methods for creating root handlers that are the basis of the application. These methods (the commonly used ones) expose Chain instance that can be used to build the application’s handler chain. The instance exposed by these methods provide a registry (via the getRegistry()) method that can be used to construct dependency injected handler instances.

See the documentation of the Guice class for example code.

12.3 Modules as plugins

Ratpack does not have a formal plugin system. However, reusable functionality can be packaged as Guice modules.

For example, that ratpack-jackson library provides the JacksonModule class which is a Guice module. To integrate Jackson into your Guice backed Ratpack application (e.g. for serializing objects as JSON), you simply use this module.

In Groovy script application this is as easy as:

import ratpack.jackson.JacksonModule
import static ratpack.jackson.Jackson.json
import static ratpack.groovy.Groovy.ratpack

ratpack {
  bindings {
    add new JacksonModule()
  }
  handlers {
    get("some-json") {
      render json(user: 1)  // will render '{user: 1}'
    }
  }
}

See the Guice package API documentation for more info on registering modules.

See the Jackson package API documentation for more info on using the Jackson integration.

12.4 Guice and the context registry

TODO guice backed registry impl

This offers an alternative to dependency injected handlers, as objects can just be retrieved on demand from the context.

More usefully, this means that Ratpack infrastructure can be integrated via Guice modules. For example, an implementation of the ServerErrorHandler can be provided by a Guice module. Because Guice bound objects are integrated into the context registry lookup mechanism, this implementation will participate in the error handling infrastructure.

This is true of all Ratpack infrastructure that works via context registry lookup, such as Renderer implementations for example.