Core Dependency Injection

/**
 * The entry point to the Guice framework. Creates Injectors from Modules.
 */
public final class Guice {
    /**
     * Creates an injector for the given set of modules in DEVELOPMENT stage.
     * @param modules Configuration modules
     * @return New Injector instance
     * @throws CreationException if one or more errors occur during injector construction
     */
    public static Injector createInjector(Module... modules);
    
    /**
     * Creates an injector for the given set of modules in DEVELOPMENT stage.
     * @param modules Configuration modules as Iterable
     * @return New Injector instance  
     * @throws CreationException if one or more errors occur during injector creation
     */
    public static Injector createInjector(Iterable<? extends Module> modules);
    
    /**
     * Creates an injector for the given set of modules in a specific stage.
     * @param stage Development stage (DEVELOPMENT, PRODUCTION, TOOL)
     * @param modules Configuration modules
     * @return New Injector instance
     * @throws CreationException if one or more errors occur during injector creation
     */
    public static Injector createInjector(Stage stage, Module... modules);
    
    /**
     * Creates an injector for the given set of modules in a specific stage.
     * @param stage Development stage (DEVELOPMENT, PRODUCTION, TOOL)  
     * @param modules Configuration modules as Iterable
     * @return New Injector instance
     * @throws CreationException if one or more errors occur during injector construction
     */
    public static Injector createInjector(Stage stage, Iterable<? extends Module> modules);
}

import com.google.inject.*;

// Simple injector creation
Injector injector = Guice.createInjector(new MyModule());

// Multiple modules
Injector injector = Guice.createInjector(
    new DatabaseModule(),
    new ServiceModule(),
    new WebModule()
);

// Production stage for optimized performance
Injector injector = Guice.createInjector(
    Stage.PRODUCTION,
    new MyModule()
);

/**
 * Builds the graphs of objects that make up your application. The injector tracks 
 * dependencies for each type and uses bindings to inject them.
 */
public interface Injector {
    /**
     * Returns the instance of the given type.
     * @param type Class to get instance of
     * @return Instance of the specified type
     * @throws ConfigurationException if binding is misconfigured
     * @throws ProvisionException if instance could not be provided
     */
    <T> T getInstance(Class<T> type);
    
    /**
     * Returns the instance bound to the given key.
     * @param key Key identifying the binding
     * @return Instance bound to the key
     * @throws ConfigurationException if binding is misconfigured
     * @throws ProvisionException if instance could not be provided
     */
    <T> T getInstance(Key<T> key);
    
    /**
     * Returns the provider for the given type.
     * @param type Class to get provider for
     * @return Provider that supplies instances of the type
     */
    <T> Provider<T> getProvider(Class<T> type);
    
    /**
     * Returns the provider bound to the given key.
     * @param key Key identifying the binding
     * @return Provider bound to the key
     */
    <T> Provider<T> getProvider(Key<T> key);
    
    /**
     * Injects dependencies into the fields and methods of an existing object.
     * @param instance Object to inject dependencies into
     */
    void injectMembers(Object instance);
    
    /**
     * Returns a members injector for the given type.
     * @param type Type to create members injector for
     * @return MembersInjector for the type
     */
    <T> MembersInjector<T> getMembersInjector(Class<T> type);
    
    /**
     * Returns a members injector for the given type literal.
     * @param typeLiteral type to get members injector for
     * @return MembersInjector for the type
     * @since 2.0
     */
    <T> MembersInjector<T> getMembersInjector(TypeLiteral<T> typeLiteral);
    
    /**
     * Returns a map of all explicit bindings.
     * @return Map of Key to Binding for all explicit bindings
     */
    Map<Key<?>, Binding<?>> getBindings();
    
    /**
     * Returns a snapshot of this injector's bindings, both explicit and just-in-time.
     * The returned map is immutable; it contains only the bindings that were
     * present when getAllBindings() was invoked.
     * @return Map of all bindings (explicit and just-in-time)
     * @since 3.0
     */
    Map<Key<?>, Binding<?>> getAllBindings();
    
    /**
     * Returns the binding for the given injection key.
     * @param key Key to get binding for
     * @return Binding for the key
     * @throws ConfigurationException if this injector cannot find or create the binding
     */
    <T> Binding<T> getBinding(Key<T> key);
    
    /**
     * Returns the binding for the given type.
     * @param type Class to get binding for
     * @return Binding for the type
     * @throws ConfigurationException if this injector cannot find or create the binding
     * @since 2.0
     */
    <T> Binding<T> getBinding(Class<T> type);
    
    /**
     * Returns the binding if it already exists, or null if it does not exist.
     * Unlike getBinding(Key), this does not attempt to create just-in-time bindings.
     * @param key Key to check for existing binding
     * @return Existing binding or null
     * @since 3.0
     */
    <T> Binding<T> getExistingBinding(Key<T> key);
    
    /**
     * Returns all explicit bindings for the given type.
     * @param type Type to find bindings for
     * @return List of bindings for the type
     */
    <T> List<Binding<T>> findBindingsByType(TypeLiteral<T> type);
    
    /**
     * Creates a child injector that inherits bindings from this injector.
     * @param modules Additional modules for the child injector
     * @return Child injector with inherited and additional bindings
     */
    Injector createChildInjector(Iterable<? extends Module> modules);
    
    /**
     * Creates a child injector that inherits bindings from this injector.
     * @param modules Additional modules for the child injector
     * @return Child injector with inherited and additional bindings
     */
    Injector createChildInjector(Module... modules);
    
    /**
     * Returns the parent injector, or null if this is a top-level injector.
     * @return Parent injector or null
     * @since 2.0
     */
    Injector getParent();
    
    /**
     * Returns a map containing all scopes in the injector.
     * @return Map of scope annotation to scope instance
     * @since 3.0
     */
    Map<Class<? extends Annotation>, Scope> getScopeBindings();
    
    /**
     * Returns a set containing all type converter bindings in the injector.
     * @return Set of type converter bindings
     * @since 3.0
     */
    Set<TypeConverterBinding> getTypeConverterBindings();
}

// Get instances directly
DatabaseService dbService = injector.getInstance(DatabaseService.class);
UserService userService = injector.getInstance(UserService.class);

// Get instances with binding annotations
Cache primaryCache = injector.getInstance(Key.get(Cache.class, Names.named("primary")));
Cache secondaryCache = injector.getInstance(Key.get(Cache.class, Names.named("secondary")));

// Get providers for lazy initialization
Provider<ExpensiveService> expensiveProvider = injector.getProvider(ExpensiveService.class);
ExpensiveService service = expensiveProvider.get(); // Created only when needed

// Inject into existing objects
MyController controller = new MyController();
injector.injectMembers(controller); // Injects @Inject fields and methods

// Create child injectors for scoped contexts
Injector requestInjector = injector.createChildInjector(new RequestModule());

/**
 * Injects dependencies into the fields and methods of existing instances.
 * @param <T> Type of object to inject into
 */
public interface MembersInjector<T> {
    /**
     * Injects dependencies into the fields and methods of the given instance.
     * @param instance Object to inject dependencies into
     */
    void injectMembers(T instance);
}

/**
 * Enumeration of injector development stages.
 */
public enum Stage {
    /**
     * Development stage with extensive error checking and validation.
     * Recommended for development and testing.
     */
    DEVELOPMENT,
    
    /**
     * Production stage with optimized performance and minimal validation.
     * Recommended for production deployments.
     */
    PRODUCTION,
    
    /**
     * Tool stage for static analysis and IDE integration.
     * Used by development tools and code generators.
     */
    TOOL
}

/**
 * Thrown when injector creation fails due to configuration problems.
 */
public class CreationException extends RuntimeException {
    /**
     * Returns the configuration messages describing the problems.
     * @return Collection of error messages
     */
    public Collection<Message> getErrorMessages();
}

/**
 * Thrown when instance provision fails.
 */
public class ProvisionException extends RuntimeException {
    /**
     * Returns the error messages describing the provision problems.
     * @return Collection of error messages
     */
    public Collection<Message> getErrorMessages();
}

/**
 * Thrown when the injector encounters configuration problems.
 */
public class ConfigurationException extends RuntimeException {
    /**
     * Returns the configuration error messages.
     * @return Collection of error messages  
     */
    public Collection<Message> getErrorMessages();
}

/**
 * Thrown from Provider.get() when an attempt is made to access a scoped object 
 * while the scope in question is not currently active.
 * @since 2.0
 */
public final class OutOfScopeException extends RuntimeException {
    public OutOfScopeException(String message);
    public OutOfScopeException(String message, Throwable cause);
    public OutOfScopeException(Throwable cause);
}