Dependency Injection with Guice

Dependency Injection with Guice

By Paul Jensen, OCI Partner

May 2007

Introduction

In the past few years, the Java community has embraced the principles of dependency injection (DI). DI frameworks such as Spring are in widespread use. Recently, a new DI framework called Guice (pronounced “juice”) has drawn attention. As opposed to more comprehensive frameworks like Spring, Guice functionality is limited almost exclusively to DI (some AOP support representing the “almost”). Guice also differs from Spring, defining wiring with Java as opposed to XML.

Guice Basics

Guice utilizes a combination of annotations and Java code to define where injection occurs and what is injected. Guice is therefore limited to use with Java 5 or later.

In order to demonstrate Guice, we will create a simple example of an order execution system comprising several services dependent upon one another in various ways. These dependencies will be resolved by Guice (effectively "wiring" the services together). The core service is the OrderService, with an implementation below which has been "Guiced".

import com.google.inject.Inject;
import com.ociweb.jnb.guice.infra.LoggingService;
 
public interface OrderService {
	void submitOrder(Order order);
}
 
public class DefaultOrderService implements OrderService {
	private final OrderDAO dao;
	private final LoggingService logger;
 
	@Inject
	public DefaultOrderService(OrderDAO dao, LoggingService logger)
	{
	this.dao = dao;
	this.logger = logger;
	}
 
	public void submitOrder(Order order) {
	// ...
	}
}

Note that the only Guice-specific code in the above is the @Inject annotation. This annotation marks an injection point. Guice will attempt to reconcile the dependencies implied by the annotated constructor, method, or field.

Constructor-based injection is generally preferred, as it provides for one-step initialization and final fields.

For method-based injection, Guice places no restriction on the name of @Inject-annotated methods (although convention dictates a setter of the form setX).

In this example, the appropriate implementations for the OrderDAO and LoggingService interfaces must be defined. Many frameworks utilize XML to express such information. In Guice, it is defined by an implementation of a Guice Module. Guice provides an AbstractModule, used here, which provides some syntactic convenience.

public class ProductionServiceModule extends AbstractModule {
 public void configure() {
	bind(OrderService.class).to(DefaultOrderService.class);
	bind(OrderDAO.class).to(JdbcOrderDAO.class); 
	bind(LoggingService.class).to(StandardLoggingService.class);
 }
}

This Module simply defines the mapping of interfaces to implementations, e.g., binding injections requiring an OrderService to the DefaultOrderService implementation. Between the module and @Inject annotations, all the structure is in place for DI.

By default, a new instance is created for each injection. For this application, singleton implementations are desired. This is accomplished by adding an in(Scopes.SINGLETON) call to the Module bindings or adding an @Singleton annotation to the implementation class.

Singletons are normally not created until needed. The method asEagerSingleton() forces object creation at Guice initialization. One or more eagerly initialized singletons can be used to control application initialization.

bind(LoggingService.class).to(StandardLoggingService.class).asEagerSingleton();

Various other scopes are defined by Guice, including ServletScopes.SESSION and ServletScopes.REQUEST. Custom scopes may also be created.

All that remains is to bootstrap the process:

public static void main(String[] args) {
	Injector injector = Guice.createInjector(new ProductionModule());
	OrderService orderService = injector.getInstance(OrderService.class);
	Order order = new Order(...);
	orderService.submitOrder(order);
}

The Injector performs the DI as defined in one or more modules (createInjector is a varargs method). It also acts as a repository for all injected objects. However looking up services in the Injector should be used sparingly, as this usage pattern (the Service Locator pattern) is precisely a usage that DI attempts to avoid.

Qualifying Injection with Annotations

The bindings so far have been strictly one interface to one implementation. If more implementations exist, they must be differentiated for injection.

As one potential solution, Guice offers a static annotation solution, parameterizing each potential injection site. Users may define custom annotations to differentiate bindings to the same type. Related bindings include an annotatedWith([AnnotationClass].class). Injections may be annotated as in the @Default annotation below:

public DefaultOrderService(@Default OrderDAO dao, LoggingService logger)

Annotations may be differentiated by attributes. Guice offers the @Named annotation which can define string identifiers. While not as typesafe as an unparameterized annotation, this approach is somewhat simpler to implement, not requiring definition of a new annotation type.

Annotations are necessary to support injection of primitive values. In the example below, the connection string for a DAO is configured in its constructor. Presumably, identical syntax would be used for the remaining DAOs.

@Inject 
public JdbcOrderDAO(
 @Named("connectionString") String connectionString)
{
 System.out.println("ConnectionString = " + connectionString);
}

The associated binding in the Module uses the Names class to create an instance of the Named annotation and associates the String value:

bindConstant().annotatedWith(Names.named("connectionString"))
 .to("jdbc:msql://localhost:1114/contact_mgr");

Providers

Often an application requires instances of multiple implementations of a given interface. For example, the OrderService may have need to submit orders to a different intermediary based on its final destination. More specifically, a Counterparty can represent a set of unique exchanges to which the order is destined. The OrderService will need to route the order request to appropriate Counterparty based on the destination exchange.

These requirements are not amenable to the injection approaches shown so far. One approach would be to utilize the Guice Provider<> interface, which acts as a factory for a particular type.

Typically a Provider will be parameterized for a single class and return an instance from its get() method. Providers can be used for lazy initialization or as a factory for multiple objects. Providers are also useful for integrating with third-party components (Guice uses them for JNDI and Spring integration) or to perform additional activities beyond initial object creation (e.g., registration, post construction initialization).

For this particular case, the Provider will return a list. Note that Providers are "in the club" (to use the Guice creator's terminology) and can participate in Dependency Injection.

bind(new TypeLiteral<List<Counterparty>>(){})
 .toProvider(CounterpartyProvider.class);

Note the use of Guice's TypeLiteral class to preserve the type parameters at runtime (see Super Type Tokens).

 @Singleton
 public class CounterpartyProvider implements Provider<List<Counterparty>> {
	private final List<Counterparty> list = new ArrayList<Counterparty>();
 
	@Inject
	public CounterpartyProvider(FixCounterparty fixCounterParty, CustomCounterparty customCounterParty) 
 {
	list.add(fixCounterParty);
	list.add(customCounterParty);
	}
 
	public List<Counterparty> get() {
	return list;
	}
 }

Which is injected into the OrderService here:

        @Inject
	@Log
	public void setCounterparties(Provider<List<Counterparty>> counterparties)  {
	       this.counterparties.addAll(counterparties.get());
	       logger.write("Added " + this.counterparties.size() + " counterparties.");
	}

Interception

In the previous section, the setCounterparties() method was annotated with @Log. This is a custom annotation created to demonstrate the AOP capabilities of Guice. The Module may define Interceptors and their join points.

import org.aopalliance.intercept.MethodInterceptor;
 
public class LoggingInterceptor implements MethodInterceptor {
 ...
	public Object invoke(MethodInvocation arg0) throws Throwable {
	loggingService.write("Invoking " + arg0.getMethod());
	return arg0.proceed();
	}
}

The bindInterceptor() method in the Module defines where to apply intercepters:

void bindInterceptor(Matcher<? super Class<?>> classMatcher,
 Matcher<? super Method> methodMatcher,
 MethodInterceptor... interceptors)

... in this case applying the LoggingInterceptor to methods with the Log annotation in all classes:

bindInterceptor(Matchers.any(), Matchers.annotatedWith(Log.class), new LoggingInterceptor());

Matches can be based on a wide variety of criteria, including annotations, class type, method return type, and containing package.

Impressions

When initially considering Guice as a topic of this article, I approached investigating "Yet another DI framework" with some trepidation. I am a proponent of DI, and I have enjoyed using Spring on several projects. Spring configuration was manageable for me, particularly using autowiring to reduce some of their complexity.

The URL references below contain opinions from a variety of individuals on Guice, typically comparing it to Spring's DI capabilities. As comparisons are unavoidable ...

• Perhaps the largest difference is that Spring is less invasive than Guice. Guice proposes including specific annotations or class references (e.g., Provider) in user code, as opposed to Spring's use of XML files. (Some annotation-based support exists for Spring - see Spring Java Configuration Project).
• Guice is typesafe, facilitating tool support such as refactoring, completion, etc. However this typesafety can make some injections more difficult. Guice uses a combination of type and annotation to define the implementation to be injected. It is not uncommon to have dependencies that cannot be defined with only these criteria.
• Guice is fast. For large applications, this may be important.
• Guice does not have support for calling lifecycle methods like Spring. Providers can support such behavior, but at a greater cost in implementation time. (Guice 1.1 may address this.)

Summary

Guice offers a new approach for DI while fully taking advantage of Java 5 annotations and generics. Some aspects of Guice have been incorporated in other frameworks (e.g., Guice is utilized in Struts 2 and Tapestry; see link below). Guice has attracted much notice in the Java community and presents an interesting alternative to other DI frameworks.