Introduction

The Intershop platform allows dependency injection via the Guice framework. This enables type-safe binding of implementations to interfaces, simple injection of members (e.g., @Inject UserMgr userMgr; ...), and makes it possible to remove static singleton access from the code.

Until now, dependencies between objects have been implicit: Somewhere in the code, some manager is used. This makes dependencies hard to detect and document, and even harder to reduce.

The Guice framework is a lightweight DI implementation that is well-documented and (now) widely used. It uses annotations and generics to declare dependencies using Java language features only. Because of that, there are no external (XML) files to be kept in sync with the actual classes (e.g., no class names as strings). Also, type safety and other typical DI problems are enforced by the compiler and supported by every Java IDE without the need for additional plug-ins.

Glossary

Overview

Involved Cartridges

• pf_objectgraph: contains the object engine and abstract object graph implementation
• pf_objectgraph_guice: contains the Guice implementation of the object graph
• tools: contains the Guice libraries

The pf_objectgraph cartridge contains the logic to instantiate ObjectGraphs being managed by an ObjectGraphEngine.

The actual DI-framework-specific ObjectGraphEngines are responsible for building and managing their ObjectGraphs.

The pf_objectgraph_guice cartridge contains one such implementation of an ObjectGraph based on the Guice framework. It is responsible for:

• Loading the object graph properties (i.e., finding modules)
• Providing an API for the legacy world to request instances and providers from an object graph

In Guice, an object graph is typically represented by an Injector. Since Injector is a Guice class, using it in Enfinity / Intershop code would lead to a hard dependency on Guice.
This is avoided by using the ObjectGraph interface and only binding an implementation (GuiceObjectGraph) encapsulating the Guice Injector to it. That way, all classes that require object graph access only depend on the ObjectGraph interface.

On application startup, all object graph declarations and modifications for all cartridges from cartridgelist.properties are read and processed (see below).

Object Graph Configuration

Object Graph Configuration - Object Graphs

The object graphs and the modules (=collections of bindings) for an object graph can be declared in a property file resources/<cartridgeName>/objectgraph/objectgraph.properties for each cartridge (i.e., each cartridge can add modules to object graphs).

# global bindings
global.modules=com.intershop.beehive.core.internal.modules.CoreNamingModule
global.overrideModules=com.customer.application.intershop.extensions.CustomerServletModule

# application type specific bindings 
local.modules = com.intershop.beehive.core.internal.feature.LocalFeatureModule
local.overrideModules = com.intershop.beehive.core.internal.feature.OverrideLocalFeatureModule

The identifier global declares that the modules are to be used in the ObjectGraph named "global". This object graph is available within the entire ICM. The identifier local declares that the modules are to be used in the application type specific ObjectGraph. These application type specific ObjectGraphs are children of the global ObjectGraph.

• Base Modules are defined by the <graphID>.modules=A B C entry in the objectgraph.properties and will get loaded into the Injector of object graph graphID. Bindings defined in these modules must be disjoint, so you can only add new bindings. The only exception is the Guice's Multibinding mechanism, where you can add items to a previously bound Multibinder or MapBinder.
• Override Modules are defined by <graphID>.overrideModules=A' D entries in the objectgraph.properties. These modules are loaded into the injector of object graph graphID and are able to override (replace) bindings defined by base modules of this object graph.

Object Graph Configuration - Modules

Each module contains bindings defining which implementation to use for injection of given interfaces.

A module might look like this:

public class CoreNamingModule extends AbstractNamingModule
{
    @Override
    protected void configure()
    {
        ...
        // bind a simple manager
        bindManager(LocaleMgr.class).to(LocaleMgrImpl.class).in(Singleton.class);
        ...
        // bind two different PasswordValidators using "named bindings"
        bindProvider(PasswordValidator.class, "PasswordExpressionValidator", named("Expression"))
                .to(PasswordExpressionValidator.class).in(Singleton.class);
        bindProvider(PasswordValidator.class, "PasswordHistoryValidator", named("History"))
                .to(PasswordHistoryValidator.class).in(Singleton.class);
        ...
        // bind a simple service
        bindService(PermissionMgmtService.class).to(PermissionMgmtServiceImpl.class).in(Singleton.class);

    }
    ...
}

Using (Injecting) Instances

Field injection (see below) now works in pipelets and preparers by default. Managers, providers and services support the whole set of injection methods (field injection, constructor injection, setter injection). Also, all classes instantiated by Guice can use injection. For details, take a look at the module classes of the appropriate cartridge.

All managers, providers and services managed by the NamingMgr can be injected.

import javax.inject.Inject;
...
public class SomePipelet extends Pipelet
{
    ...
    @Inject
    protected SessionMgr sessionMgr;

    @Inject
    private DomainMgr domainMgr;

    @Inject
    private AuthorizationMgr authMgr;

    @Inject
    private UserPOFactory userFactory;

    @Inject @Named(StringEncodingUtils.ENCODING_HTML) 
    private StringEncodingProvider htmlEncoder;
    ...
}

The injected fields can then be used directly.

Injection Is Supported in Classes

• Declared classes at Guice modules
  • Former managers and providers
• Instances created by the component framework, e.g.,
  • BusinessObjectExtensionFactories
  • ServiceDefinitions
• Pipelets
• DBInit and DBMigrate preparer

Using Injection in Unsupported Classes

Unsupported classes are classes which are not instantiated by the Guice injector and the context was not injected by the class that instantiates the object. The use of injection in such classes is a sham, because the object itself defines the context and this is not the intention of dependency injection. Using the annotation @Inject in that cases can be a preparation, nothing more. The question is: How to support instantiation and injection in such classes?

Factory Classes

The instantiation of objects should be located in a factory class:

public interface MyFactory
{
    MyObject createMyObject(parameter ...);
}

and the according implementation:

public class MyFactoryImpl implements MyFactory
{
    @Inject
    private Injector injector;
    @Inject
    private CurrentApplicationBOProvider provider;
 
    MyObject createMyObject(parameter ...)
    {
      MyObject result = new MyObjectImpl(parameter);
      injector.injectMembers(result);
      return result;
    }
 
    MyObject createMyObjectWithInjection(parameter ...)
    {
      return new MyObjectImpl(provider, parameter);
    }
}

At the beginning, it looks a little bit confusing (additional interface and implementation), but if you collect the instantiation of your cartridge in that factory class you have several advantages:

• The object creation logic is placed at a one place and can be replaced.
• You can decide to call injectMembers(result).
• You can avoid injection, using constructor to add injectable objects, without adding parameters to the factory method.
• You can change the implementation class without adapting all classes which instanciate the implementation class.
• It is possible to put multiple methods in such a class, so the number of classes is increased by TWO.
• The implementation of the factory class can be replaced in projects easier than replacing all implementation, which using new operator to instantiate that class.
• You can instantiate the class MyObjectImpl in test cases in another context (e.g., using mocks to encapsulate the test).

Last but not least, the binding is necessary in your cartridge or test module.

bind(MyFactory.class).to(MyFactoryImpl.class).asEagerSingleton();

Now your implementation does not depend on the injection context (injector). But now you need to get access to the factory, it does not solve the original problem to get access to an object, which is injectable, you need access to an object graph.

Injection in Business Objects

Most business object does not support injection for performance reasons, so @Inject MyFactory; is not available. But the BusinessObjectContext contains the object graph, which was used to create the context.

class MyBusinessObjectImplWithFactory implements BusinessObject
{
    private MyObject createMyObject()
    {
        return getContext().getObjectGraph().getInstance(MyFactory.class).createMyObject(parameter);
    }
}
 
class MyBusinessObjectImplWithoutFactory implements BusinessObject
{
    private MyObject createMyObject()
    {
        MyObject result = new MyObjectImpl(parameter);
        getContext().getObjectGraph().injectMembers(result);
        return result;
    }
}

Other Cases

First, try to get an object graph or Guice injector. This will avoid the fallback to the global single static object path.

If that is impossible, the last option is to use the global object graph of the NamingMgr.

class MyImplWithoutFactory
{
    private MyObject createMyObject()
    {
        return NamingMgr.getObjectGraph().getInstance(MyFactory.class).createMyObject(parameter);
    }

    private MyObject createMyObject()
    {
        MyObjectBO result = new MyObjectImpl(parameter);
        NamingMgr.injectMembers(result);
        return result;
    }
}

Scopes

Normally, Guice will create a new instance each time a value is injected. This is perfect for objects that are stateless and inexpensive to instantiate.
The @Singleton scope will be used where previously GoF Singletons (static access) were used, i.e., managers, providers etc.

The scope of an object can be defined:

• In bindings (recommended for flexibility)

  import javax.inject.Singleton;
  import com.google.inject.AbstractModule;
  ...
  public class CoreNamingModule extends AbstractModule
  {
      ...
      @Override
      protected void configure()
      {
          ...
          bind(NamingMgrImpl.class).in(Singleton.class);
          ...
      }
      ...
  }
  

• As an annotation of the class:

  import javax.inject.Singleton;
  
  ...
  
  @Singleton
  public class NamingMgrImpl extends NamingMgr
  {
      ...
  }
  

• By annotating @Provides methods

  import javax.inject.Singleton;
  import com.google.inject.Provides;
  ...
  public class SomeModule
  {
      ...
      @Provides @Singleton
      public ApplicationServerMgr getApplicationServerMgr(ServerEnvironment serverEnvironment)
      {
          return serverEnvironment.getApplicationServerMgr();
      }
      ...
  }
  

Dependency Injection on Startup

At the server startup, all object graph declarations and modifications for all cartridges from cartridgelist.properties are read and processed. After that, the bindings are known, and instances can be requested. Guice now also has the information it needs to instantiate classes in the correct order (resolving inter-dependencies).

When an instance of class SomeClass is requested, Guice instantiates the class bound to SomeClass in the processed modules. If for example, SomeClassImpl is bound to SomeClass, it will instantiate SomeClassImpl. All required fields which are annotated using @Inject will be instantiated too, and so on for all classes needed (recursively).

Since the object graph can be accessed via the NamingMgr, the server startup works almost as before.