Bootstrapping

Governator creates two Guice injectors: an internal “bootstrapping” Injector and the main application Injector. The main Injector is created when you call LifecycleInjectorBuilder.createInjector(). The bootstrapping injector is created internally by Governator.

Why Two Injectors?

Several Governator features have recursive dependencies. Configuration Mapping requires ConfigurationProvider instances. Auto Binding arguments require AutoBindProvider instances. These instances are needed as the main Injector is being created (i.e. as Guice is creating instances).

Bootstrapping Steps

Bootstrapping is part of the classpath scanning step:

• ConfigurationProvider classes annotated with @AutoBindSingleton are detected and bound into the bootstrap Injector.
• AutoBindProvider classes must be bound in the bootstrapping step
• Application specific bootstrap binding (if any) is done via the bootstrap module

LifecycleInjector.builder().withBootstrapModule(yourBootstrapModule)

The bootstrap module is passed a special Guice Binder that has an additional method for binding ConfigurationProviders. Always use this special method:

  /**
   * Use this to bind {@link ConfigurationProvider}s. Do NOT use standard Guice binding.
   *
   * @return configuration binding builder
   */
  public LinkedBindingBuilder<ConfigurationProvider> bindConfigurationProvider();

Module transformations

The {@link ModuleTransform} provides a mechanism to apply a final transformation to all of the modules that will be installed on the main injector. These transformations can include filtering or augmenting of bindings in the modules. Several transformation recipes from Guice’s wiki are included: {@link StripStaticInjections} and {@link WarnAboutStaticInjections}. Binding overrides are also implemented using this mechanism (Coming soon…)

Post injector creation action

The {@link PostInjectorAction} provides a mechanism to specify an operation to perform immediately after the injector is created but before it is returned. This service is provided as part of Guice since it makes it easy to capture common post injector creation operation. For example, log a report on all bindings {@link BindingReport}, create all bound singletons eagerly (for DEVELOPMENT mode) {@link CreateAllBoundSingletons}, auto-start the lifecycle manager {@link LifecycleManagerStarter}, generate a dot diagram {@link GrapherAction}, etc…

LifecycleListener

You can bind a LifecycleListener in the bootstrap module. See the LifecycleListener wiki for details.

AutoBindProvider

You must bind any AutoBindProvider instances in the bootstrap module. See the Auto Binding wiki for details.

Completion

At the end of Bootstrapping, Governator creates the bootstrap injector and gets the LifecycleManager instance which manages the main injection phase. Any bound configuration providers, lifecycle listeners and auto bind providers are injected into the LifecycleManager.

Testing

JUnit @Rule for testing with the LifecycleManager.

@Bootstrap

@Bootstrap offers syntactic sugar on top of the LifecycleInjectorBuilder. With @Bootstrap a single main application configuration class can contain multiple parameterized annotations though which
the LifecycleInjectorBuilder is configured. The Injector can then be created with just one call.

Injector injector = LifecycleInjector.bootstrap(MyApplicationConfiguration.class);

@Application(name="foo")
public class MyApplicationConfiguration extends AbstractModule {
   void configure() {
      bind(SomeService.class).asEagerSingleton();
   }
}

In the above example MyApplicationConfiguration uses the @Application bootstrap annotations to create bindings based on the parameters of the @Application annotation. In addition MyApplicationConfiguration is a Guice module and will be added to the injector.

The @Application annotation exposes configuration options to the caller and specified a LifecycleInjectorBuilderSuite that will perform the actual bindings.

@Documented
@Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
@Bootstrap(ApplicationBootstrap.class)
public static @interface Application {
    String name();
}

ApplicationBootstrap will be instantiated by Governator

public static class ApplicationBootstrap implements LifecycleInjectorBuilderSuite {
    private Application application;
        
    @Inject
    public ApplicationBootstrap(Application application) {
        this.application = application;
    }
        
    @Override
    public void configure(LifecycleInjectorBuilder builder) {
        builder.withModules(new AbstractModule() {
            @Override
            protected void configure() {
                bind(String.class).annotatedWith(Names.named("application")).toInstance(application.name());
            }
        });
    }
}