Gaelyk Guice Plugin ![Build Status](https://camo.githubusercontent.com/f8fa665a43fc7154d79afeb4b6a13f934fa22ff7ff6e5e608d1cc8aefc27f9e3/68747470733a2f2f6275696c64686976652e636c6f7564626565732e636f6d2f6a6f622f657264692f6a6f622f6761656c796b2d67756963652d706c7567696e2f62616467652f69636f6e)
This plugin provides support for using Guice as a Dependency Injection mechanism for Gaelyk applications.
Installation
There are several steps to install the plugin and set up your application to use Guice for Dependency Injection.
Adding the dependency on the plugin
Plugin is available from maven central, so you need to specify that repository and add a new dependency in the Gradle build file of your project:
repositories {
mavenCentral()
}
dependencies {
compile 'org.gaelyk:gaelyk-guice-plugin:0.1'
}
Modifying web.xml
To be able to use the plugin you need to modify web.xml
file of your application.
Installing GuiceFilter
NOTE: This step is not necessary if you do not need to use Request or Session scopes in your dependencies.
Add the following to web.xml
.
<filter>
<filter-name>guiceFilter</filter-name>
<filter-class>com.google.inject.servlet.GuiceFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>guiceFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Installing GaelykGuiceFilter
Add the following to web.xml
.
<filter>
<filter-name>gaelykGuiceFilter</filter-name>
<filter-class>groovyx.gaelyk.plugin.guice.GaelykGuicePluginFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>gaelykGuiceFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Extending GuiceServletContextListener
to define dependencies
As an example let's say that we have a service class that has a String dependency:
class MyService {
String injected
@Inject
MyService(String injected) {
this.injected = injected
}
}
Dependencies in Guice are resolved using an Injector
instance. To provide one you need to extend GuiceServletContextListener
and implement getInjector()
method. We will therefore define how our String dependency can be resolved with MyGuiceServletContextListener
.
class MyGuiceServletContextListener extends GuiceServletContextListener {
@Override
protected Injector getInjector() {
Guice.createInjector(new AbstractModule() {
@Override
protected void configure() {
bind(String).toInstance('Hello world!')
}
});
}
}
With our dependency graph defined we can now add MyGuiceServletContextListener
to web.xml
:
<listener>
<listener-class>MyGuiceServletContextListener</listener-class>
</listener>
Usage
Plugin adds injectDependencies(Object... definitions)
method to groovlets that can be used to easily inject dependencies into them but it also provides access to the Injector
instance created from your implementation of GuiceServletContextListener
for more advanced usages.
Using injectDependencies()
After installing the plugin there is a new method available in groovlets called injectDependencies()
. It accepts a list of injection definitions which can define injections by type, injections by name and injections by qualifier. You can provide as many definitions to one injectDependencies()
call as you wish.
Injection by type
If a dependency definition passed to a injectDependencies()
call is a class then the resolved dependency will be injected under uncapitalized class name.
Given the example service and binding specified in the Installation section the following code in a groovlet will pass:
injectDependencies MyService
assert myService.injected == 'Hello World!'
Injection by name
If a dependency definition passed to a injectDependencies()
call is a Key
instance and the binding annotation of that key is a @Named
instance then the resolved dependency will be injected under the value of the annotation.
Given the following binding specified in your module class:
bind(String).annotatedWith(Names.named('helloWorld')).toInstance('Hello World!')
The following code in a groovlet will pass:
injectDependencies Key.get(String, Names.named('helloWorld'))
assert helloWorld == 'Hello World!'
Injection by qualifier
If a dependency definition passed to a injectDependencies()
call is a Key
instance and the binding annotation type is defferent than @Named
instance then the resolved dependency will be injected under uncapitalized class name of the binding annotation.
Given the following binding specified in your module class:
bind(Map).annotatedWith(RequestParameters).toInstance([id: 123])
The following code in a groovlet will pass:
injectDependencies Key.get(Map, RequestParameters)
assert requestParameters.id == 123
Using Injector
directly
In situations when you need more control over the names under which dependencies are injected into the binding of the groovlet you can always fall back to using the Injector
directly. An Injector
instance is bound under injector
in your groovlets. Given the example service and binding specified in the Installation section you can inject a MyService
instance under a different name with the following code:
differentNameForMyService = injector.getInstance(MyService)
assert differentNameForMyService.injected == 'Hello World!'
Unit testing groovlets that use plugin features
It is quite easy to mock injectDependencies()
method. As it is using injector#getInstance(Class)
and injector#getInstance(Key)
under the covers all that you have to do is mock those methods and apply InjectDependenciesCategory
using spock.util.mop.Use
to you specification. Given an example groovlet, called simpleInjection.groovy
:
injectDependencies MyService
request.hello = myService.injected
Following is how a unit test for it might look like:
@Use(InjectDependenciesCategory)
class SimpleInjectionSpec extends ConventionalGaelykUnitSpec {
Injector injector = Mock(Injector)
void setup() {
simpleInjection.injector = injector
}
void "groovlets that use injection can be unit tested"() {
given:
injector.getInstance(MyService) >> new MyService('Hello world!')
when:
simpleInjection.get()
then:
simpleInjection.request.hello == 'Hello world!'
}
}