Module Configuration

/**
 * A module contributes configuration information, typically interface bindings,
 * which will be used to create an Injector.
 */
public interface Module {
    /**
     * Contributes bindings and other configurations for this module to binder.
     * Do not invoke this method directly to install submodules. Instead use
     * Binder.install(Module), which ensures that @Provides provider methods are discovered.
     * @param binder The binder to configure
     */
    void configure(Binder binder);
}

/**
 * AbstractModule is a helper class used to add bindings to the Guice injector.
 * Simply extend this class and implement configure(), then call the inherited
 * methods which mirror those found in Binder.
 */
public abstract class AbstractModule implements Module {
    /**
     * Configures a Binder via the exposed methods. Override this method
     * to define your module's bindings.
     */
    protected void configure() {}
    
    /**
     * Creates a binding for the given type.
     * @param clazz Type to bind
     * @return Binding builder for further configuration
     */
    protected <T> AnnotatedBindingBuilder<T> bind(Class<T> clazz);
    
    /**
     * Creates a binding for the given key.
     * @param key Key to bind
     * @return Binding builder for further configuration  
     */
    protected <T> LinkedBindingBuilder<T> bind(Key<T> key);
    
    /**
     * Creates a binding for the given type literal.
     * @param typeLiteral Type literal to bind
     * @return Binding builder for further configuration
     */
    protected <T> AnnotatedBindingBuilder<T> bind(TypeLiteral<T> typeLiteral);
    
    /**
     * Binds a constant value.
     * @return Constant binding builder
     */
    protected AnnotatedConstantBindingBuilder bindConstant();
    
    /**
     * Installs another module into this module.
     * @param module Module to install
     */
    protected void install(Module module);
    
    /**
     * Binds a scope annotation to a scope implementation.
     * @param scopeAnnotation Scope annotation class
     * @param scope Scope implementation
     */
    protected void bindScope(Class<? extends Annotation> scopeAnnotation, Scope scope);
    
    /**
     * Binds method interceptors to methods matched by class and method matchers.
     * @param classMatcher Matcher for classes to intercept
     * @param methodMatcher Matcher for methods to intercept
     * @param interceptors Method interceptors to apply
     */
    protected void bindInterceptor(
        Matcher<? super Class<?>> classMatcher,
        Matcher<? super Method> methodMatcher,
        MethodInterceptor... interceptors
    );
    
    /**
     * Requests injection of static fields and methods.
     * @param type Type with static members to inject
     */
    protected void requestStaticInjection(Class<?>... types);
    
    /**
     * Adds an error message to be reported during injector creation.
     * @param message Error message
     * @param arguments Message format arguments
     */
    protected void addError(String message, Object... arguments);
    
    /**
     * Adds an error message to be reported during injector creation.
     * @param t Throwable representing the error
     */
    protected void addError(Throwable t);
    
    /**
     * Adds an error message to be reported during injector creation.
     * @param message Error message object
     */
    protected void addError(Message message);
    
    /**
     * Returns the current binder.
     * @return Current binder instance
     */
    protected Binder binder();
    
    /**
     * Gets a provider for the given key.
     * @param key Key to get provider for
     * @return Provider for the key
     * @since 2.0
     */
    protected <T> Provider<T> getProvider(Key<T> key);
    
    /**
     * Gets a provider for the given type.
     * @param type Type to get provider for
     * @return Provider for the type
     * @since 2.0
     */
    protected <T> Provider<T> getProvider(Class<T> type);
    
    /**
     * Gets a members injector for the given type.
     * @param type Type to get members injector for
     * @return MembersInjector for the type
     * @since 2.0
     */
    protected <T> MembersInjector<T> getMembersInjector(Class<T> type);
    
    /**
     * Gets a members injector for the given type literal.
     * @param type TypeLiteral to get members injector for
     * @return MembersInjector for the type
     * @since 2.0
     */
    protected <T> MembersInjector<T> getMembersInjector(TypeLiteral<T> type);
    
    /**
     * Returns the current stage.
     * @return Current injector creation stage
     * @since 2.0
     */
    protected Stage currentStage();
}

public class DatabaseModule extends AbstractModule {
    @Override
    protected void configure() {
        // Bind interface to implementation
        bind(DatabaseService.class).to(PostgreSQLService.class);
        
        // Bind with annotations
        bind(Cache.class).annotatedWith(Names.named("primary"))
                         .to(RedisCache.class)
                         .in(Singleton.class);
        
        // Bind to instance
        bind(String.class).annotatedWith(Names.named("dbUrl"))
                          .toInstance("jdbc:postgresql://localhost/mydb");
        
        // Install other modules
        install(new ConfigurationModule());
        install(new LoggingModule());
    }
    
    // Provider methods
    @Provides
    @Singleton
    DatabaseConnection provideConnection(@Named("dbUrl") String url) {
        return DriverManager.getConnection(url);
    }
}

/**
 * Collects configuration information (primarily bindings) which will be used
 * to create an Injector.
 */
public interface Binder {
    /**
     * Creates a binding for the given type.
     * @param type Type to bind
     * @return Binding builder for configuration
     */
    <T> AnnotatedBindingBuilder<T> bind(Class<T> type);
    
    /**
     * Creates a binding for the given key.
     * @param key Key to bind
     * @return Binding builder for configuration
     */
    <T> LinkedBindingBuilder<T> bind(Key<T> key);
    
    /**
     * Creates a binding for the given type literal.
     * @param typeLiteral Type literal to bind
     * @return Binding builder for configuration
     */
    <T> LinkedBindingBuilder<T> bind(TypeLiteral<T> typeLiteral);
    
    /**
     * Binds a constant value.
     * @return Constant binding builder
     */
    AnnotatedConstantBindingBuilder bindConstant();
    
    /**
     * Installs the given module.
     * @param module Module to install
     */
    void install(Module module);
    
    /**
     * Binds a scope annotation to a scope implementation.
     * @param annotationType Scope annotation
     * @param scope Scope implementation
     */
    void bindScope(Class<? extends Annotation> annotationType, Scope scope);
    
    /**
     * Binds method interceptors.
     * @param classMatcher Class matcher
     * @param methodMatcher Method matcher  
     * @param interceptors Interceptors to bind
     */
    void bindInterceptor(
        Matcher<? super Class<?>> classMatcher,
        Matcher<? super Method> methodMatcher,
        MethodInterceptor... interceptors
    );
    
    /**
     * Gets the current stage.
     * @return Current development stage
     */
    Stage currentStage();
    
    /**
     * Records an error message.
     * @param message Error message
     * @param arguments Format arguments
     */
    void addError(String message, Object... arguments);
    
    /**
     * Records an error.
     * @param t Throwable to record
     */
    void addError(Throwable t);
    
    /**
     * Records an error message.
     * @param message Message to record
     */
    void addError(Message message);
    
    /**
     * Returns a binder that skips class loading and method scanning.
     * @return Restricted binder
     */
    Binder skipSources(Class<?>... classesToSkip);
    
    /**
     * Returns a binder that uses the given source for newly created elements.
     * @param source Source object
     * @return Binder with specified source
     */
    Binder withSource(Object source);
}

/**
 * Builder for bindings that can be annotated.
 * @param <T> Type being bound
 */
public interface AnnotatedBindingBuilder<T> extends LinkedBindingBuilder<T> {
    /**
     * Annotates the binding with the given annotation type.
     * @param annotationType Annotation type
     * @return LinkedBindingBuilder for further configuration
     */
    LinkedBindingBuilder<T> annotatedWith(Class<? extends Annotation> annotationType);
    
    /**
     * Annotates the binding with the given annotation instance.
     * @param annotation Annotation instance
     * @return LinkedBindingBuilder for further configuration
     */
    LinkedBindingBuilder<T> annotatedWith(Annotation annotation);
}

/**
 * Builder for specifying binding targets.
 * @param <T> Type being bound
 */
public interface LinkedBindingBuilder<T> extends ScopedBindingBuilder {
    /**
     * Binds to the given implementation class.
     * @param implementation Implementation class
     * @return ScopedBindingBuilder for scope configuration
     */
    ScopedBindingBuilder to(Class<? extends T> implementation);
    
    /**
     * Binds to the given key.
     * @param targetKey Target key  
     * @return ScopedBindingBuilder for scope configuration
     */
    ScopedBindingBuilder to(Key<? extends T> targetKey);
    
    /**
     * Binds to the given type literal.
     * @param implementation Target type literal
     * @return ScopedBindingBuilder for scope configuration
     */
    ScopedBindingBuilder to(TypeLiteral<? extends T> implementation);
    
    /**
     * Binds to a provider class.
     * @param providerType Provider class
     * @return ScopedBindingBuilder for scope configuration
     */
    ScopedBindingBuilder toProvider(Class<? extends Provider<? extends T>> providerType);
    
    /**
     * Binds to a provider key.
     * @param providerKey Provider key
     * @return ScopedBindingBuilder for scope configuration
     */
    ScopedBindingBuilder toProvider(Key<? extends Provider<? extends T>> providerKey);
    
    /**
     * Binds to a provider instance.
     * @param provider Provider instance
     * @return ScopedBindingBuilder for scope configuration
     */
    ScopedBindingBuilder toProvider(Provider<? extends T> provider);
    
    /**
     * Binds to the given instance.
     * @param instance Instance to bind to
     */
    void toInstance(T instance);
    
    /**
     * Binds to the given constructor.
     * @param constructor Constructor to bind to
     * @return ScopedBindingBuilder for scope configuration
     */
    <S extends T> ScopedBindingBuilder toConstructor(Constructor<S> constructor);
    
    /**
     * Binds to the given constructor with type literal.
     * @param constructor Constructor to bind to
     * @param type Type literal for the constructor's declaring class
     * @return ScopedBindingBuilder for scope configuration
     */
    <S extends T> ScopedBindingBuilder toConstructor(Constructor<S> constructor, TypeLiteral<? extends S> type);
}

/**
 * Builder for specifying binding scope.
 */
public interface ScopedBindingBuilder {
    /**
     * Scopes the binding with the given scope annotation.
     * @param scopeAnnotation Scope annotation
     */
    void in(Class<? extends Annotation> scopeAnnotation);
    
    /**
     * Scopes the binding with the given scope.
     * @param scope Scope implementation
     */
    void in(Scope scope);
    
    /**
     * Scopes the binding as an eager singleton.
     */
    void asEagerSingleton();
}

/**
 * Builder for binding constants.
 */
public interface ConstantBindingBuilder {
    /**
     * Binds to a string value.
     * @param value String value
     */
    void to(String value);
    
    /**
     * Binds to an int value.
     * @param value int value
     */
    void to(int value);
    
    /**
     * Binds to a long value.
     * @param value long value
     */
    void to(long value);
    
    /**
     * Binds to a boolean value.
     * @param value boolean value
     */
    void to(boolean value);
    
    /**
     * Binds to a double value.
     * @param value double value
     */
    void to(double value);
    
    /**
     * Binds to a float value.
     * @param value float value
     */
    void to(float value);
    
    /**
     * Binds to a byte value.
     * @param value byte value
     */
    void to(byte value);
    
    /**
     * Binds to a short value.
     * @param value short value
     */
    void to(short value);
    
    /**
     * Binds to a char value.
     * @param value char value
     */
    void to(char value);
    
    /**
     * Binds to a Class value.
     * @param value Class value
     */
    void to(Class<?> value);
    
    /**
     * Binds to an enum value.
     * @param value Enum value
     */
    <E extends Enum<E>> void to(E value);
}