public abstract class Guice extends Object
Any non trivial application will require supporting objects for the handler implementations, for persistence for example. These supporting objects can be managed by Guice and made available to handlers (either by dependency injection or registry lookup) for increased reusability, modularity and testability.
The Guice integration is not part of the Ratpack core library, but is available as a separate add on.
That said, Ratpack is designed to support something like Guice as an integral piece via it's Registry
abstraction.
Guice is the “official” solution.
The user entry point for Ratpack applications is the HandlerFactory
implementation
that is given to the LaunchConfigBuilder.build(ratpack.launch.HandlerFactory)
method.
This implementation can use one of the handler(...)
static methods.
Below is a complete example for bootstrapping a Guice based Ratpack application.
import ratpack.handling.*; import ratpack.registry.*; import ratpack.guice.*; import ratpack.launch.*; import ratpack.util.*; import com.google.inject.*; import javax.inject.*; // Some service to be dependency injected class SomeService {} // A Guice module that provides the service class ServiceModule extends AbstractModule { protected void configure() { bind(SomeService.class); } } // An action that registers the module with the registry, making it part of the application class ModuleBootstrap implements Action<ModuleRegistry> { public void execute(ModuleRegistry modules) { modules.register(new ServiceModule()); } } // A handler implementation that is dependency injected @Singleton class InjectedHandler implements Handler { private final SomeService service; @Inject public InjectedHandler(SomeService service) { this.service = service; } public void handle(Context exchange) { // … } } // A chain configurer that adds a dependency injected handler to the chain class HandlersBootstrap implements Action<Chain> { public void execute(Chain chain) { // The registry in a Guice backed chain can be used to retrieve objects that were bound, // or to create objects that are bound “just-in-time”. Registry<Object> registry = chain.getRegistry(); Handler injectedHandler = registry.get(InjectedHandler.class); // Add the handler into the chain chain.get("some/path", injectedHandler); } } // A HandlerFactory implementation used to bootstrap the application class MyHandlerFactory implements HandlerFactory { public Handler create(LaunchConfig launchConfig) { return Guice.handler(launchConfig, new ModuleBootstrap(), new HandlersBootstrap()); } } // Building a launch config with our handler factory LaunchConfig launchConfig = LaunchConfigBuilder.baseDir(new File("appRoot")).build(new MyHandlerFactory());
There are two ways to use Guice bound objects in your handler implementations.
The handler()
methods used to create a Guice backed application take an Action
that operates on a Chain
instance.
This chain instance given to this action provides a Guice backed Registry
via its Chain.getRegistry()
method.
This registry is able to retrieve objects that were explicitly bound (i.e. defined by a module), and bind objects “just in time”.
This means that it can be used to construct dependency injected Handler
implementations.
Simply pass the class of the handler implementation to create a new dependency injected instance of to this method, then add it to the chain.
See the code above for an example of this.
The Context
object that is given to a handler's Handler.handle(ratpack.handling.Context)
method is also a registry implementation. In a Guice backed app, Guice bound objects can be retrieved via the Registry.get(Class)
method of
the context. You can retrieve any bound object via its publicly bound type.
However, this will not create “just-in-time” bindings. Only objects that were explicitly bound can be retrieved this way.
Add on Ratpack functionality is typically provided via Guice modules.
For example, the Jackson integration for JSON serialisation
is provided by the ratpack-jackson
add-on which ships a Guice module.
To use its functionality simply register the module it provides with the ModuleRegistry
used to bootstrap the application.
The Ratpack Groovy add-on provides application modes that automatically incorporate Guice (namely the “Ratpack Script” mode). The module registration process is simpler and more convenient in this mode, and there are additional options for obtaining Guice bound objects.
See the Groovy add-on's documentation for more details.
Modifier and Type | Method and Description |
---|---|
static Transformer<Module,Injector> |
childInjectorFactory(Injector parent)
Creates a transformer that can build an injector from a module, as a child of the given parent.
|
static Handler |
handler(LaunchConfig launchConfig,
Action<? super ModuleRegistry> moduleConfigurer,
Action<? super Chain> chainConfigurer)
Creates a handler that can be used as the entry point for a Guice backed Ratpack app.
|
static Handler |
handler(LaunchConfig launchConfig,
Action<? super ModuleRegistry> moduleConfigurer,
Transformer<? super Injector,? extends Handler> injectorTransformer)
Creates a handler that can be used as the entry point for a Guice backed Ratpack app.
|
static Handler |
handler(LaunchConfig launchConfig,
Injector parentInjector,
Action<? super ModuleRegistry> moduleConfigurer,
Action<? super Chain> chainConfigurer)
Creates a handler that can be used as the entry point for a Guice backed Ratpack app.
|
static Handler |
handler(LaunchConfig launchConfig,
Injector parentInjector,
Action<? super ModuleRegistry> moduleConfigurer,
Transformer<? super Injector,? extends Handler> injectorTransformer)
Creates a handler that can be used as the entry point for a Guice backed Ratpack app.
|
static Registry |
justInTimeRegistry(Injector injector)
|
static Transformer<Module,Injector> |
newInjectorFactory(LaunchConfig launchConfig)
Creates a transformer that can build an injector from a module.
|
static Registry |
registry(Injector injector)
|
public static Handler handler(LaunchConfig launchConfig, Action<? super ModuleRegistry> moduleConfigurer, Action<? super Chain> chainConfigurer) throws Exception
Modules are processed eagerly. Before this method returns, the modules will be used to create a single Injector
instance.
This injector is available to the given handler via service lookup.
launchConfig
- The launch config of the servermoduleConfigurer
- The configurer of the ModuleRegistry
to back the created handlerchainConfigurer
- The configurer that builds the handler chainChain
given to chainConfigurer
.Exception
public static Handler handler(LaunchConfig launchConfig, Action<? super ModuleRegistry> moduleConfigurer, Transformer<? super Injector,? extends Handler> injectorTransformer) throws Exception
This is a lower level version of handler(ratpack.launch.LaunchConfig, ratpack.util.Action, ratpack.util.Action)
that supports a custom final Handler
creation strategy.
launchConfig
- The launch config of the servermoduleConfigurer
- The configurer of the ModuleRegistry
to back the created handlerinjectorTransformer
- Takes the final Injector
instance that was created from the modules and returns the Handler
to useChain
given to chainConfigurer
.Exception
public static Handler handler(LaunchConfig launchConfig, Injector parentInjector, Action<? super ModuleRegistry> moduleConfigurer, Action<? super Chain> chainConfigurer) throws Exception
Similar to handler(ratpack.launch.LaunchConfig, ratpack.util.Action, ratpack.util.Action)
,
but provides the opportunity to use a parent injector when creating the injector to use for the application.
See Guice documentation for the semantics of parent/child injectors.
Typically only required when making a Ratpack application a component of a larger application.
launchConfig
- The launch config of the serverparentInjector
- The injector to use as a parent of the injector to be createdmoduleConfigurer
- The configurer of the ModuleRegistry
to back the created handlerchainConfigurer
- The configurer that builds the handler chainChain
given to chainConfigurer
.Exception
public static Handler handler(LaunchConfig launchConfig, Injector parentInjector, Action<? super ModuleRegistry> moduleConfigurer, Transformer<? super Injector,? extends Handler> injectorTransformer) throws Exception
This is a lower level version of handler(ratpack.launch.LaunchConfig, com.google.inject.Injector, ratpack.util.Action, ratpack.util.Action)
that supports a custom final Handler
creation strategy.
launchConfig
- The launch config of the serverparentInjector
- The injector to use as a parent of the injector to be createdmoduleConfigurer
- The configurer of the ModuleRegistry
to back the created handlerinjectorTransformer
- Takes the final Injector
instance that was created from the modules and returns the Handler
to useChain
given to chainConfigurer
.Exception
public static Registry justInTimeRegistry(Injector injector)
Registry
backed by the given Injector
that will create objects via “just-in-time” binding.
Typically used in conjuction with the Handlers.chain(LaunchConfig, ratpack.registry.Registry, ratpack.util.Action)
method.
injector
- The injector to back the registrypublic static Registry registry(Injector injector)
Registry
backed by the given Injector
that will NOT create objects via “just-in-time” binding.injector
- The injector to back the registrypublic static Transformer<Module,Injector> newInjectorFactory(LaunchConfig launchConfig)
The module given to the transform()
method may be null
.
public static Transformer<Module,Injector> childInjectorFactory(Injector parent)
The module given to the transform()
method may be null
.