{"id":487,"date":"2008-03-14T00:00:00","date_gmt":"2008-03-13T16:00:00","guid":{"rendered":"http:\/\/www.strongd.net\/?p=487"},"modified":"2011-07-15T09:36:22","modified_gmt":"2011-07-15T01:36:22","slug":"java-on-guice","status":"publish","type":"post","link":"https:\/\/www.strongd.net\/?p=487","title":{"rendered":"Java on Guice"},"content":{"rendered":"

Java on Guice
<\/FONT>Guice 1.0 User’s Guide<\/FONT><\/STRONG>

\n


<\/P>
\n


<\/P>
\n

Guice<\/I> (pronounced “juice”) is an ultra-lightweight, next-generation dependency injection container for Java 5 and later.
<\/P>
\n

Introduction
<\/H1>
\n

The enterprise Java community exerts a lot of effort toward wiring objects together. How does your web application get access to a middle tier service, or your service to the logged in user or transaction manager? You’ll find many general and specific solutions to this problem. Some rely on patterns. Others use frameworks. All result in varying degrees of testability and some amount of boilerplate code. You’ll soon see that Guice enables the best of all worlds: easy unit testing, maximal flexibility and maintainability, and minimal repetition.<\/P>

\n

We’ll use an unrealistically simple example to illustrate the benefits of Guice over some classic approaches which you’re probably already familiar with. The following example is so simple in fact that, even though it will show immediate benefits, we won’t actually do Guice justice. We hope you’ll see that as your application grows, Guice’s benefits accelerate.
<\/P>

\n

In this example, a client depends on a service interface. This could be any arbitrary service. We’ll just call it Service<\/SPAN>.
<\/P>
\n


<\/DIV>
\n

public interface Service {
<\/P>
\n

  void go();<\/SPAN>
}<\/SPAN>
<\/P>

\n

We have a default implementation of this service which the client should not depend directly on. If we decide to use a different service implementation in the future, we don’t want to go around and change all of our clients.<\/P>
\n


<\/P>
\n

public class ServiceImpl implements Service {
<\/P>
\n

  public void go() {<\/P>
\n

    …<\/P>
\n

  }<\/P>
\n

}<\/SPAN> <\/P>
\n


We also have a mock service which we can use in unit tests.<\/P>

\n

public class MockService implements Service {<\/P>
\n


<\/P>
\n

  private boolean gone = false;<\/SPAN>

  public void go() {<\/SPAN>
    gone = true;<\/SPAN>
  }<\/SPAN>

  public boolean isGone() {<\/SPAN>
    return gone;<\/SPAN>
  }<\/SPAN>
}<\/SPAN>
<\/P>
\n

Plain Old Factories<\/H2>
\n
Before we discovered dependency injection, we mostly used the factory pattern. In addition to the service interface, you have a service factory which provides the service to clients as well as a way for tests to pass in a mock service. We’ll make the service a singleton so we can keep this example as simple as possible.


\n
public class ServiceFactory {<\/SPAN>

  private ServiceFactory() {}<\/SPAN>
    <\/SPAN>
  private static Service instance = new ServiceImpl();<\/SPAN>

  public static Service getInstance() {<\/SPAN>
    return instance;<\/SPAN>
  }<\/SPAN>
  <\/SPAN>
  public static void setInstance(Service service) {<\/SPAN>
    instance = service;<\/SPAN>
  }<\/SPAN>
} <\/SPAN>
<\/DIV>
<\/DIV>
\n

Our client goes directly to the factory every time it needs a service.
<\/P>

\n

public class Client {

  public void go() {
    Service service = ServiceFactory.getInstance();
    service.go();
  }
}
<\/DIV>
\n


<\/P>
\n

The client is simple enough, but the unit test for the client has to pass in a mock service and then remember to clean up afterwards. This isn’t such a big deal in our simple example, but as you add more clients and services, all this mocking and cleaning up creates friction for unit test writing. Also, if you forget to clean up after your test, other tests may succeed or fail when they shouldn’t. Even worse, tests may fail depending on which order you run them in.
<\/P>

\n

public void testClient() {
  Service previous = ServiceFactory.getInstance();
  try {
    final MockService mock = new MockService();
    ServiceFactory.setInstance(mock);
    Client client = new Client();
    client.go();
    assertTrue(mock.isGone());
  }
  finally {
    ServiceFactory.setInstance(previous);
  }
}
<\/P>
\n


<\/P>
\n

Finally, note that the service factory’s API ties us to a singleton approach. Even if getInstance()<\/SPAN> could return multiple instances, setInstance()<\/SPAN> ties our hands. Moving to a non-singleton implementation would mean switching to a more complex API.
<\/P>
\n

Dependency Injection By Hand
<\/H2>
\n
The dependency injection pattern aims in part to make unit testing easier. We don’t necessarily need a specialized framework to practice dependency injection. You can get roughly 80% of the benefit writing code by hand.

While the client asked the factory for a service in our previous example, with dependency injection, the client expects to have its dependency passed in. Don’t call me, I’ll call you, so to speak.


\n
public class Client {
   
  private final Service service;

  public Client(Service service) {
    this.service = service;
  }

  public void go() {
    service.go();
  }
}
<\/DIV>
<\/DIV>
\n
This simplifies our unit test considerably. We can just pass in a mock service and throw everything away when we’re done.
<\/DIV>
\n


\n
public void testClient() {<\/SPAN>
  MockService mock = new MockService();<\/SPAN>
  Client client = new Client(mock);<\/SPAN>
  client.go();<\/SPAN>
  assertTrue(mock.isGone());<\/SPAN>
}<\/SPAN>
<\/DIV>
<\/DIV>
\n
We can also tell from the API exactly what the client depends on.

Now, how do we connect the client with a service? When implementing dependency injection by hand, we can move all dependency logic into factory classes. This means we need a factory for our client, too.
<\/DIV>
\n


\n
public static class ClientFactory {

  private ClientFactory() {}

  public static Client getInstance() {
    Service service = ServiceFactory.getInstance();
    return new Client(service);
  }
}
<\/DIV>
<\/DIV>
\n
Implementing dependency injection by hand requires roughly the same number of lines of code as plain old factories.
<\/DIV>
\n

Dependency Injection with Guice<\/H2>
\n
Writing factories and dependency injection logic by hand for every service and client can become tedious. Some other dependency injection frameworks even require you to explicitly map services to the places where you want them injected.

Guice aims to eliminate all of this boilerplate without sacrificing maintainability.

With Guice, you implement modules. Guice passes a binder to your module, and your module uses the binder to map interfaces to implementations. The following module tells Guice to map Service<\/SPAN> to ServiceImpl<\/SPAN> in singleton scope:


\n
public class MyModule implements Module {<\/SPAN>
  public void configure(Binder binder) {<\/SPAN>
    binder.bind(Service.class)<\/SPAN>
      .to(ServiceImpl.class)<\/SPAN>
      .in(Scopes.SINGLETON);<\/SPAN>
  }<\/SPAN>
}<\/SPAN>
<\/DIV>
<\/DIV>
\n
A module tells Guice what we want to inject. Now, how do we tell Guice where we want it injected? With Guice, you annotate constructors, methods and fields with @Inject<\/SPAN>.
<\/DIV>
\n


\n
public class Client {

  private final Service service;

  @Inject<\/B>
  public Client(Service service) {
    this.service = service;
  }

  public void go() {
    service.go();
  }
}
<\/DIV>
<\/DIV>
\n
The @Inject<\/SPAN> annotation makes it clear to a programmer editing your class which members are injected.

For Guice to inject Client<\/SPAN>, we must either directly ask Guice to create a Client<\/SPAN> instance for us, or some other class must have Client<\/SPAN> injected into it.
<\/DIV>
\n

Guice vs. Dependency Injection By Hand<\/H3>
\n
As you can see, Guice saves you from having to write factory classes. You don’t have to write explicit code wiring clients to their dependencies. If you forget to provide a dependency, Guice fails at startup. Guice handles circular dependencies automatically.

Guice enables you to specify scopes declaratively. For example, you don’t have to write the same code to store an object in the HttpSession<\/SPAN> over and over.

In the real world, you often don’t know an implementation class until runtime. You need meta factories or service locators for your factories. Guice addresses these problems with minimal effort.

When injecting dependencies by hand, you can easily slip back into old habits and introduce direct dependencies, especially if you’re new to the concept of dependency injection. Using Guice turns the tables and makes doing the right thing easier. Guice helps keep you on track.
<\/DIV>
\n

More Annotations<\/H2>
\n
When possible, Guice enables you to use annotations in lieu of explicit bindings and eliminate even more boilerplate code. Back to our example, if you need an interface to simplify unit testing but you don’t care about compile time dependencies, you can point to a default implementation directly from your interface.


\n
@ImplementedBy(ServiceImpl.class)<\/B>
public interface Service {
  void go();
}
<\/DIV>
<\/DIV>
\n
If a client needs a Service<\/SPAN> and Guice can’t find an explicit binding, Guice will inject an instance of ServiceImpl<\/SPAN>.

By default, Guice injects a new instance every time. If you want to specify a different scope, you can annotate the implementation class, too.
<\/DIV>
\n


\n
@Singleton<\/B>
public class ServiceImpl implements Service {
  public void go() {
    …
  }
}
<\/DIV><\/DIV>
\n

Architectural Overview<\/H1>
\n
We can break Guice’s architecture down into two distinct stages: startup and runtime. You build an Injector<\/SPAN> during startup and use it to inject objects at runtime.
<\/DIV>
\n

Startup<\/H2>
\n
You configure Guice by implementing Module<\/SPAN>. You pass Guice a module, Guice passes your module a Binder<\/SPAN>, and your module uses the binder to configure bindings. A binding most commonly consists of a mapping between an interface and a concrete implementation. For example:


\n
public class MyModule implements Module {<\/SPAN>
  public void configure(Binder binder) {<\/SPAN>
    \/\/ Bind Foo to FooImpl. Guice will create a new
    \/\/ instance of FooImpl for every injection.
    binder.bind(Foo.class)<\/SPAN>.to(FooImpl.class);

    \/\/ Bind Bar to an instance of Bar.
    Bar bar = new Bar();
    binder.bind(Bar.class).toInstance(bar);
<\/SPAN>  }<\/SPAN>
}<\/SPAN>
<\/DIV>
<\/DIV>
\n
Guice can look at the classes you tell it about during this stage and any classes those classes know about, and tell you whether or not you’re missing any dependencies. For example, in a Struts 2 application, Guice knows about all of your actions. Guice can validate your actions and anything they transitively depend on, and fail early if necessary.

Creating an Injector<\/SPAN> entails the following steps:
<\/DIV>
\n

<\/DIV>
\n

<\/P>

\n


    \n
  1. First, create an instance of your module and pass it to Guice.createInjector()<\/SPAN>.
    \n
  2. Guice creates a Binder<\/SPAN> and passes it to your module.
    \n
  3. Your module uses the binder to define bindings.
    \n
  4. Based on the bindings you specified, Guice creates an Injector<\/SPAN> and returns it to you.
    \n
  5. You use the injector to inject an object.<\/LI><\/OL>
    \n

    Runtime<\/H2>
    \n
    We can now use the injector we created during the first stage to inject objects and introspect on our bindings. Guice’s runtime model consists of an injector which contains some number of bindings.


    \n

    <\/DIV>
    <\/DIV>
    \n
    A Key<\/SPAN> uniquely identifies each binding. The key consists of a type which the client depends on and an optional annotation. You can use an annotation to differentiate multiple bindings to the same type. The key’s type and annotation correspond to the type and annotation at a point of injection.

    Each binding has a provider which provides instances of the necessary type. You can provide a class, and Guice will create instances of it for you. You can give Guice an instance of the type you’re binding to. You can implement your own provider, and Guice can inject dependencies into it.

    Each binding also has an optional scope. Bindings have no scope by default, and Guice creates a new instance for every injection. A custom scope enables you to control whether or not Guice creates a new instance. For example, you can create one instance per HttpSession<\/SPAN>.<\/DIV>
    \n

    Bootstrapping Your Application
    <\/H2>
    \n
    The idea of bootstrapping<\/I> is fundamental to dependency injection. Always explicitly asking the Injector<\/SPAN> for dependencies would be using Guice as a service locator, not a dependency injection framework.

    Your code should deal directly with the Injector<\/SPAN> as little as possible. Instead, you want to bootstrap your application by injecting one root object. The container can further inject dependencies into the root object’s dependencies, and so on recursively. In the end, your application should ideally have one class (if that many) which knows about the Injector<\/SPAN>, and every other class should expect to have dependencies injected.

    For example, a web application framework such as Struts 2 bootstraps your application by injecting all of your actions. You might bootstrap a web service framework by injecting your service implementation classes.

    Dependency injection is viral. If you’re refactoring an existing code base with a lot of static methods, you may start to feel like you’re pulling a never-ending thread. This is a Good Thing. It means dependency injection is making your code more flexible and testable.

    If you get in over your head, rather than try to refactor an entire code base all in one shot, you might temporarily<\/I> store a reference to the Injector<\/SPAN> in a static field somewhere or use static injection. Name the field’s class clearly though: Injector<\/SPAN>Hack<\/SPAN> and GodKillsAKittenEveryTimeYouUseMe<\/SPAN> come to mind. Keep in mind that you you’ll have to mock this class, and your unit tests will have to install an Injector here by hand, and remember to clean up afterwards.
    <\/DIV>
    \n

    Binding Dependencies <\/H1>
    \n
    How does Guice know what to inject? For starters, a Key<\/A> composed of a type and an optional annotation uniquely identifies a dependency. Guice refers to the mapping between a key and an implementation as a Binding<\/A>. An implementation can consist of a single object, a class which Guice should also inject, or a custom provider.


    \n

    When injecting a dependency, Guice first looks for an explicit<\/I> binding, a binding which you specified using the Binder<\/A>. The Binder<\/SPAN> API uses the builder pattern to create a domain-specific expression language. Different methods return different objects depending on the context limiting you to appropriate methods.<\/P>
    \n


    <\/P>
    \n

    For example, to bind an interface Service<\/SPAN> to a concrete implementation ServiceImpl<\/SPAN>, call: <\/P>

    \n

    binder.bind(Service.class).to(ServiceImpl.class);<\/SPAN>
    <\/DIV>
    <\/DIV>
    \n
    This binding matches the following the method:
    <\/DIV>
    \n


    \n
    @Inject
    void injectService(Service service) {
      …
    }
    <\/DIV>
    \n
    <\/DIV><\/DIV>
    \n

    \n
    Note: <\/B>In contrast to some other frameworks, Guice gives no special treatment to “setter” methods. Guice will inject any method with any number of parameters so long as the method has an @Inject<\/SPAN> annotation, even if the method is in a superclass.
    <\/DIV><\/BLOCKQUOTE>
    \n

    DRY (Don’t Repeat Yourself)<\/B>
    <\/H3>
    \n
    Repeating “binder<\/SPAN>” over and over for each binding can get a little tedious. Guice provides a Module<\/SPAN> support class named AbstractModule<\/A> which implicitly gives you access to Binder<\/SPAN>‘s methods. For example, we could extend AbstractModule<\/SPAN> and rewrite the above binding as:
    <\/DIV>
    <\/SPAN>
    \n
    bind(Service.class)<\/SPAN>.to(ServiceImpl.class);<\/SPAN>
    <\/DIV>

    \n

    We’ll use this syntax throughout the rest of the guide.
    <\/P>
    \n

    Annotating Bindings
    <\/H2>
    \n
    If you need multiple bindings to the same type, you can differentiate the bindings with annotations.  For example, to bind an interface Service<\/SPAN> and annotation @Blue<\/SPAN> to the concrete implementation BlueService<\/SPAN>, call:


    \n
    bind(Service.class)<\/SPAN>
      .annotatedWith(Blue.class)<\/B><\/SPAN>
      .to(BlueService.class);<\/SPAN>
    <\/DIV>
    <\/DIV>
    \n
    This binding matches the following the method:
    <\/DIV>
    \n


    \n
    @Inject
    void injectService(@Blue<\/B> Service service) {
      …
    }
    <\/DIV>
    <\/DIV>
    \n
    Notice that while @Inject<\/SPAN> goes on the method, binding annotations such as @Blue<\/SPAN> go directly on the parameter. The same goes for constructors. When using field injection, both annotations can apply directly to the field, as in this example:


    \n
    @Inject @Blue<\/B> Service service;
    <\/DIV><\/DIV>
    \n

    Creating Binding Annotations<\/B><\/H3>
    \n

    \n

    <\/H3>Where did this @Blue<\/SPAN> annotation just mentioned come from?  You can create such an annotation easily, although the standard incantation you have to use is unfortunately a little complex:


    \n
    \/**<\/SPAN>
     * Indicates we want the blue version of a binding.<\/SPAN>
     *\/<\/SPAN>
    @Retention(RetentionPolicy.RUNTIME)<\/SPAN>
    @Target({ElementType.FIELD, ElementType.PARAMETER})<\/SPAN>
    @BindingAnnotation<\/SPAN>
    public @interface Blue {}<\/SPAN>
    <\/DIV>
    Luckily, we don’t really have to understand it all just to use it.  But for the curious, here’s what all this boilerplate means:


    \n