src/com/google/inject/ContainerBuilder.java

/**
 * Copyright (C) 2006 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.inject;

import com.google.inject.util.Objects;
import static com.google.inject.util.Objects.nonNull;
import com.google.inject.spi.ErrorMessage;

import java.lang.reflect.Member;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Properties;
import java.util.Set;
import java.util.LinkedHashSet;
import java.util.logging.Logger;

/**
 * Builds a dependency injection {@link Container}. Binds {@link Key}s to
 * implementations. For example, a binding implementation could be anything
 * from a constant value to an object in the HTTP session.
 *
 * <p>Not safe for concurrent use.
 *
 * <p>Default bindings include:
 *
 * <ul>
 *   <li>A {@code Factory<T>} for each binding of type {@code T}
 *   <li>The {@link Container} iself
 *   <li>The {@link Logger} for the class being injected
 * </ul>
 *
 * <p>Converts constants as needed from {@code String} to any primitive type
 * in addition to {@code enum} and {@code Class<?>}.
 *
 * @author crazybob@google.com (Bob Lee)
 */
public final class ContainerBuilder {

  private static final Logger logger =
      Logger.getLogger(ContainerBuilder.class.getName());

  final List<BindingBuilder<?>> bindingBuilders =
      new ArrayList<BindingBuilder<?>>();
  final List<ConstantBindingBuilder> constantBindingBuilders =
      new ArrayList<ConstantBindingBuilder>();
  final List<LinkedBindingBuilder<?>> linkedBindingBuilders =
      new ArrayList<LinkedBindingBuilder<?>>();
  final Map<String, Scope> scopes = new HashMap<String, Scope>();

  final List<Class<?>> staticInjections = new ArrayList<Class<?>>();

  boolean created;

  /**
   * Keeps error messages in order and prevents duplicates.
   */
  Set<ErrorMessage> errorMessages = new LinkedHashSet<ErrorMessage>();

  private static final InternalFactory<Container> CONTAINER_FACTORY =
      new InternalFactory<Container>() {
        public Container get(InternalContext context) {
          return context.getContainer();
        }
      };

  private static final InternalFactory<Logger> LOGGER_FACTORY =
      new InternalFactory<Logger>() {
        public Logger get(InternalContext context) {
          Member member = context.getExternalContext().getMember();
          return member == null ? Logger.getAnonymousLogger()
              : Logger.getLogger(member.getDeclaringClass().getName());
        }
      };

  static final String UNKNOWN_SOURCE = "[unknown source]";

  static final Scope DEFAULT_SCOPE = new Scope() {
    public <T> Factory<T> scope(Key<T> key, Factory<T> creator) {
      // We actually optimize around this.
      throw new UnsupportedOperationException();
    }
  };

  /**
   * Constructs a new builder.
   */
  public ContainerBuilder() {
    put(Scopes.DEFAULT, DEFAULT_SCOPE);
    put(Scopes.SINGLETON, SingletonScope.INSTANCE);

    bind(Container.class).to(CONTAINER_FACTORY);
    bind(Logger.class).to(LOGGER_FACTORY);
  }

  final List<Validation> validations = new ArrayList<Validation>();

  /**
   * Registers a type to be validated for injection when we create the
   * container.
   */
  void validate(final Object source, final Class<?> type) {
    validations.add(new Validation() {
      public void run(ContainerImpl container) {
        ErrorHandler previous = container.getErrorHandler();
        try {
          container.setErrorHandler(new ConfigurationErrorHandler(source));
          container.getConstructor(type);
        } finally {
          container.setErrorHandler(previous);
        }
      }
    });
  }

  interface Validation {
    void run(ContainerImpl container);
  }

  /**
   * Creates an object pointing to the current location within the
   * configuration. If we run into a problem later, we'll be able to trace it
   * back to the original source. Useful for debugging. The default
   * implementation returns {@code ContainerBuilder}'s caller's {@code
   * StackTraceElement}.
   */
  protected Object source() {
    // Search up the stack until we find a class outside of this one.
    for (final StackTraceElement element : new Throwable().getStackTrace()) {
      String className = element.getClassName();
      if (!className.equals(ContainerBuilder.class.getName())
          && !className.equals(AbstractModule.class.getName()))
        return element.getFileName() + ":" 
            + element.getLineNumber() + ":";
    }
    throw new AssertionError();
  }

  /**
   * Maps a {@link Scope} instance to a given scope name. Scopes should be
   * mapped before used in bindings. @{@link Scoped#value()} references this
   * name.
   */
  public void put(String name, Scope scope) {
    if (scopes.containsKey(nonNull(name, "name"))) {
      add(new ErrorMessage(source(), "Scope named '" + name
          + "' is already defined."));
    } else {
        scopes.put(nonNull(name, "name"), nonNull(scope, "scope"));
    }
  }

  /**
   * Binds the given key.
   */
  public <T> BindingBuilder<T> bind(Key<T> key) {
    ensureNotCreated();
    BindingBuilder<T> builder = new BindingBuilder<T>(key).from(source());
    bindingBuilders.add(builder);
    return builder;
  }

  /**
   * Binds the given type.
   */
  public <T> BindingBuilder<T> bind(TypeToken<T> typeToken) {
    return bind(Key.get(typeToken));
  }

  /**
   * Binds the given type.
   */
  public <T> BindingBuilder<T> bind(Class<T> clazz) {
    return bind(Key.get(clazz));
  }

  /**
   * Links the given key to another key effectively creating an alias for a
   * binding.
   */
  public <T> LinkedBindingBuilder<T> link(Key<T> key) {
    ensureNotCreated();
    LinkedBindingBuilder<T> builder =
        new LinkedBindingBuilder<T>(key).from(source());
    linkedBindingBuilders.add(builder);
    return builder;
  }

  /**
   * Binds a constant to the given name.
   */
  public ConstantBindingBuilder bind(String name) {
    ensureNotCreated();
    return bind(name, source());
  }

  /**
   * Binds a constant to the given name from the given source.
   */
  private ConstantBindingBuilder bind(String name, Object source) {
    ConstantBindingBuilder builder =
        new ConstantBindingBuilder(Objects.nonNull(name, "name")).from(source);
    constantBindingBuilders.add(builder);
    return builder;
  }

  /**
   * Binds a string constant for each property.
   */
  public void bindProperties(Map<String, String> properties) {
    ensureNotCreated();
    Object source = source();
    for (Map.Entry<String, String> entry : properties.entrySet()) {
      String key = entry.getKey();
      String value = entry.getValue();
      bind(key, source).to(value);
    }
  }

  /**
   * Binds a string constant for each property.
   */
  public void bindProperties(Properties properties) {
    ensureNotCreated();
    Object source = source();
    for (Map.Entry<Object, Object> entry : properties.entrySet()) {
      String key = (String) entry.getKey();
      String value = (String) entry.getValue();
      bind(key, source).to(value);
    }
  }

  /**
   * Upon successful creation, the {@link Container} will inject static fields
   * and methods in the given classes.
   *
   * @param types for which static members will be injected
   */
  public void requestStaticInjection(Class<?>... types) {
    staticInjections.addAll(Arrays.asList(types));
  }

  /**
   * Applies the given module to this builder.
   */
  public void apply(Module module) {
    module.configure(this);    
  }

  /**
   * Adds an error message to be reported at creation time.
   */
  void add(ErrorMessage errorMessage) {
    errorMessages.add(errorMessage);
  }

  /**
   * Creates a {@link Container} instance. Injects static members for classes
   * which were registered using {@link #requestStaticInjection(Class...)}.
   *
   * @param loadSingletons If true, the container will load all singletons
   *  now. If false, the container will lazily load singletons. Eager loading
   *  is appropriate for production use while lazy loading can speed
   *  development.
   * @throws IllegalStateException if called more than once
   */
  public Container create(boolean loadSingletons) {
    ensureNotCreated();
    created = true;

    HashMap<Key<?>, InternalFactory<?>> factories =
        new HashMap<Key<?>, InternalFactory<?>>();
    ContainerImpl container = new ContainerImpl(factories);

    for (ConstantBindingBuilder builder : constantBindingBuilders) {
      if (builder.hasValue()) {
        Key<?> key = builder.getKey();
        InternalFactory<?> factory = builder.getInternalFactory();
        factories.put(key, factory);
      } else {
        add(new ErrorMessage(builder.getSource(),
            "Constant value isn't set."));
      }
    }

    final List<ContainerImpl.ContextualCallable<Void>> singletonLoaders =
        new ArrayList<ContainerImpl.ContextualCallable<Void>>();

    for (BindingBuilder<?> builder : bindingBuilders) {
      final Key<?> key = builder.getKey();
      final InternalFactory<?> factory = builder.getInternalFactory(container);
      factories.put(key, factory);

      if (builder.isSingleton()) {
        singletonLoaders.add(new ContainerImpl.ContextualCallable<Void>() {
          public Void call(InternalContext context) {
            context.setExternalContext(
                ExternalContext.newInstance(null, key,
                    context.getContainerImpl()));
            try {
              factory.get(context);
              return null;
            } finally {
              context.setExternalContext(null);
            }
          }
        });
      }
    }

    for (LinkedBindingBuilder<?> builder : linkedBindingBuilders) {
      // TODO: Support alias to a later-declared alias.
      Key<?> destination = builder.getDestination();
      if (destination == null) {
        add(new ErrorMessage(builder.getSource(),
            "Link destination isn't set."));
        continue;
      }

      InternalFactory<?> factory = factories.get(destination);
      if (factory == null) {
        add(new ErrorMessage(builder.getSource(),
            "Destination of link binding not found: " + destination));
        continue;
      }

      factories.put(builder.getKey(), factory);
    }

    // Run validations.
    for (Validation validation : validations) {
      validation.run(container);
    }

    if (!errorMessages.isEmpty()) {
      StringBuilder error = new StringBuilder();
      error.append("Configuration errors:\n");
      for (ErrorMessage errorMessage : errorMessages) {
        error.append(errorMessage).append('\n');
      }
      logger.severe(error.toString());
      throw new ConfigurationException("Encountered configuration errors."
        + " See the log for details.");
    }
    container.setErrorHandler(new RuntimeErrorHandler());

    container.injectStatics(staticInjections);

    if (loadSingletons) {
      container.callInContext(new ContainerImpl.ContextualCallable<Void>() {
        public Void call(InternalContext context) {
          for (ContainerImpl.ContextualCallable<Void> singletonLoader
              : singletonLoaders) {
            singletonLoader.call(context);
          }
          return null;
        }
      });
    }

    return container;
  }

  /**
   * Currently we only support creating one Container instance per builder.
   * If we want to support creating more than one container per builder,
   * we should move to a "factory factory" model where we create a factory
   * instance per Container. Right now, one factory instance would be
   * shared across all the containers, singletons synchronize on the
   * container when lazy loading, etc.
   */
  private void ensureNotCreated() {
    if (created) {
      throw new IllegalStateException("Container already created.");
    }
  }

  /**
   * Binds a {@link Key} to an implementation in a given scope.
   */
  public class BindingBuilder<T> {

    Object source = ContainerBuilder.UNKNOWN_SOURCE;
    Key<T> key;
    InternalFactory<? extends T> factory;
    Scope scope;

    BindingBuilder(Key<T> key) {
      this.key = nonNull(key, "key");
    }

    Key<T> getKey() {
      return key;
    }

    BindingBuilder<T> from(Object source) {
      this.source = source;
      return this;
    }

    /**
     * Sets the name of this binding.
     */
    public BindingBuilder<T> named(String name) {
      if (!this.key.hasDefaultName()) {
        add(new ErrorMessage(source, "Name set more than once."));
      }

      this.key = this.key.named(name);
      return this;
    }

    /**
     * Binds to instances of the given implementation class. The {@link
     * Container} will inject the implementation instances as well. Sets the
     * scope based on the @{@link Scoped} annotation on the implementation
     * class if present.
     */
    public <I extends T> BindingBuilder<T> to(Class<I> implementation) {
      return to(TypeToken.get(implementation));
    }

    /**
     * Binds to instances of the given implementation type. The {@link
     * Container} will inject the implementation instances as well. Sets the
     * scope based on the @{@link Scoped} annotation on the implementation
     * class if present.
     */
    public <I extends T> BindingBuilder<T> to(TypeToken<I> implementation) {
      ensureImplementationIsNotSet();
      validate(source, implementation.getRawType());
      this.factory = new DefaultFactory<I>(implementation);
      setScopeFromType(implementation.getRawType());
      return this;
    }

    private void setScopeFromType(Class<?> implementation) {
      Scoped scoped = implementation.getAnnotation(Scoped.class);
      if (scoped != null) {
        in(scoped.value());
      }
    }

    /**
     * Binds to instances from the given factory.
     */
    public BindingBuilder<T> to(
        final ContextualFactory<? extends T> factory) {
      ensureImplementationIsNotSet();

      this.factory = new InternalFactory<T>() {
        public T get(InternalContext context) {
          return factory.get(context.getExternalContext());
        }

        public String toString() {
          return factory.toString();
        }
      };

      return this;
    }

    /**
     * Binds to instances from the given factory.
     */
    public BindingBuilder<T> to(final Factory<? extends T> factory) {
      ensureImplementationIsNotSet();

      this.factory = new InternalFactory<T>() {
        public T get(InternalContext context) {
          return factory.get();
        }

        public String toString() {
          return factory.toString();
        }
      };

      return this;
    }

    /**
     * Binds to the given instance.
     */
    BindingBuilder<T> to(T instance) {
      ensureImplementationIsNotSet();
      this.factory = new ConstantFactory<T>(instance);
      return this;
    }

    /**
     * Binds to instances from the given factory.
     */
    BindingBuilder<T> to(final InternalFactory<? extends T> factory) {
      ensureImplementationIsNotSet();
      this.factory = factory;
      return this;
    }

    /**
     * Adds an error message if the implementation has already been bound.
     */
    private void ensureImplementationIsNotSet() {
      if (factory != null) {
        add(new ErrorMessage(source, "Implementation set more than once."));
      }
    }

    /**
     * Specifies the scope. References the name passed to {@link
     * ContainerBuilder#put(String, Scope)}.
     */
    public BindingBuilder<T> in(String scopeName) {
      ensureScopeNotSet();

      // We could defer this lookup to when we create the container, but this
      // is fine for now.
      this.scope = scopes.get(scopeName);
      if (this.scope == null) {
        add(new ErrorMessage(source, "Scope named '" + scopeName
            + "' not found."));
      }
      return this;
    }

    /**
     * Specifies the scope.
     */
    public BindingBuilder<T> in(Scope scope) {
      ensureScopeNotSet();

      this.scope = nonNull(scope, "scope");
      return this;
    }

    private void ensureScopeNotSet() {
      if (this.scope != null) {
        add(new ErrorMessage(source, "Scope set more than once."));
      }
    }

    InternalFactory<? extends T> getInternalFactory(
        final ContainerImpl container) {
      // If an implementation wasn't specified, use the injection type.
      if (this.factory == null) {
        to(key.getTypeToken());
      }

      if (scope == null || scope == DEFAULT_SCOPE) {
        return this.factory;
      }

      // TODO: This is a little hairy.
      final InternalFactory<? extends T> internalFactory = this.factory;
      final Factory<T> factory = scope.scope(this.key, new Factory<T>() {
        public T get() {
          return container.callInContext(
              new ContainerImpl.ContextualCallable<T>() {
            public T call(InternalContext context) {
              return internalFactory.get(context);
            }
          });
        }

        public String toString() {
          return internalFactory.toString();
        }
      });

      return new InternalFactory<T>() {
        public T get(InternalContext context) {
          return factory.get();
        }

        public String toString() {
          return factory.toString();
        }
      };
    }

    boolean isSingleton() {
      return this.scope == SingletonScope.INSTANCE;
    }

    /**
     * Injects new instances of the specified implementation class.
     */
    private class DefaultFactory<I extends T> implements InternalFactory<I> {

      volatile ContainerImpl.ConstructorInjector<I> constructor;

      private final TypeToken<I> implementation;

      public DefaultFactory(TypeToken<I> implementation) {
        // TODO: Ensure this is a concrete implementation.
        this.implementation = implementation;
      }

      @SuppressWarnings("unchecked")
      public I get(InternalContext context) {
        if (constructor == null) {
          // This unnecessary cast is a workaround for an annoying compiler
          // bug I keep running into.
          Object c = context.getContainerImpl().getConstructor(implementation);
          this.constructor = (ContainerImpl.ConstructorInjector<I>) c;
        }
        return (I) constructor.construct(context, key.getRawType());
      }

      public String toString() {
        return implementation.toString();
      }
    }
  }

  /**
   * Builds a constant binding.
   */
  public class ConstantBindingBuilder {

    final String name;
    Class<?> type;
    Object value;
    Object source = ContainerBuilder.UNKNOWN_SOURCE;

    ConstantBindingBuilder(String name) {
      this.name = name;
    }

    Key<?> getKey() {
      return Key.get(type, name);
    }

    boolean hasValue() {
      return type != null;
    }

    Object getSource() {
      return source;
    }

    InternalFactory<?> getInternalFactory() {
      return new ConstantFactory<Object>(value);
    }

    ConstantBindingBuilder from(Object source) {
      this.source = source;
      return this;
    }

    /**
     * Binds constant to the given value.
     */
    public void to(String value) {
      to(String.class, value);
    }

    /**
     * Binds constant to the given value.
     */
    public void to(int value) {
      to(int.class, value);
    }

    /**
     * Binds constant to the given value.
     */
    public void to(long value) {
      to(long.class, value);
    }

    /**
     * Binds constant to the given value.
     */
    public void to(boolean value) {
      to(boolean.class, value);
    }

    /**
     * Binds constant to the given value.
     */
    public void to(double value) {
      to(double.class, value);
    }

    /**
     * Binds constant to the given value.
     */
    public void to(float value) {
      to(float.class, value);
    }

    /**
     * Binds constant to the given value.
     */
    public void to(short value) {
      to(short.class, value);
    }

    /**
     * Binds constant to the given value.
     */
    public void to(char value) {
      to(char.class, value);
    }

    /**
     * Binds constant to the given value.
     */
    public void to(Class<?> value) {
      to(Class.class, value);
    }

    /**
     * Binds constant to the given value.
     */
    public <E extends Enum<E>> void to(E value) {
      to(value.getDeclaringClass(), value);
    }

    /**
     * Maps a constant value to the given type and name.
     */
    <T> void to(final Class<T> type, final T value) {
      this.type = type;
      this.value = value;
    }
  }

  /**
   * Links one binding to another.
   */
  public class LinkedBindingBuilder<T> {

    Key<T> key;
    Key<? extends T> destination;
    Object source = ContainerBuilder.UNKNOWN_SOURCE;

    LinkedBindingBuilder(Key<T> key) {
      this.key = key;
    }

    Object getSource() {
      return source;
    }

    Key<T> getKey() {
      return key;
    }

    Key<? extends T> getDestination() {
      return destination;
    }

    LinkedBindingBuilder<T> from(Object source) {
      this.source = source;
      return this;
    }

    /**
     * Links to another binding with the given key.
     */
    public void to(Key<? extends T> destination) {
      this.destination = destination;
    }
  }

  class ConfigurationErrorHandler implements ErrorHandler {

    final Object source;

    ConfigurationErrorHandler(Object source) {
      this.source = source;
    }

    public void handle(String message) {
      add(new ErrorMessage(source, message));
    }

    public void handle(Throwable t) {
      add(new ErrorMessage(source, t.getMessage()));
    }
  }

  class RuntimeErrorHandler implements ErrorHandler {

    public void handle(String message) {
      throw new ConfigurationException(message);
    }

    public void handle(Throwable t) {
      throw new ConfigurationException(t);
    }
  }
}