core/src/com/google/inject/multibindings/OptionalBinder.java

/*
 * Copyright (C) 2014 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.multibindings;

import static com.google.inject.internal.RealOptionalBinder.newRealOptionalBinder;

import com.google.common.base.Optional;
import com.google.inject.Binder;
import com.google.inject.Key;
import com.google.inject.TypeLiteral;
import com.google.inject.binder.LinkedBindingBuilder;
import com.google.inject.internal.RealOptionalBinder;

/**
 * An API to bind optional values, optionally with a default value. OptionalBinder fulfills two
 * roles:
 *
 * <ol>
 * <li>It allows a framework to define an injection point that may or may not be bound by users.
 * <li>It allows a framework to supply a default value that can be changed by users.
 * </ol>
 *
 * <p>When an OptionalBinder is added, it will always supply the bindings: {@code Optional<T>} and
 * {@code Optional<Provider<T>>}. If {@link #setBinding} or {@link #setDefault} are called, it will
 * also bind {@code T}.
 *
 * <p>{@code setDefault} is intended for use by frameworks that need a default value. User code can
 * call {@code setBinding} to override the default. <b>Warning: Even if setBinding is called, the
 * default binding will still exist in the object graph. If it is a singleton, it will be
 * instantiated in {@code Stage.PRODUCTION}.</b>
 *
 * <p>If setDefault or setBinding are linked to Providers, the Provider may return {@code null}. If
 * it does, the Optional bindings will be absent. Binding setBinding to a Provider that returns null
 * will not cause OptionalBinder to fall back to the setDefault binding.
 *
 * <p>If neither setDefault nor setBinding are called, it will try to link to a user-supplied
 * binding of the same type. If no binding exists, the optionals will be absent. Otherwise, if a
 * user-supplied binding of that type exists, or if setBinding or setDefault are called, the
 * optionals will return present if they are bound to a non-null value.
 *
 * <p>Values are resolved at injection time. If a value is bound to a provider, that provider's get
 * method will be called each time the optional is injected (unless the binding is also scoped, or
 * an optional of provider is injected).
 *
 * <p>Annotations are used to create different optionals of the same key/value type. Each distinct
 * annotation gets its own independent binding.
 *
 * <pre><code>
 * public class FrameworkModule extends AbstractModule {
 *   protected void configure() {
 *     OptionalBinder.newOptionalBinder(binder(), Renamer.class);
 *   }
 * }</code></pre>
 *
 * <p>With this module, an {@link Optional}{@code <Renamer>} can now be injected. With no other
 * bindings, the optional will be absent. Users can specify bindings in one of two ways:
 *
 * <p>Option 1:
 *
 * <pre><code>
 * public class UserRenamerModule extends AbstractModule {
 *   protected void configure() {
 *     bind(Renamer.class).to(ReplacingRenamer.class);
 *   }
 * }</code></pre>
 *
 * <p>or Option 2:
 *
 * <pre><code>
 * public class UserRenamerModule extends AbstractModule {
 *   protected void configure() {
 *     OptionalBinder.newOptionalBinder(binder(), Renamer.class)
 *         .setBinding().to(ReplacingRenamer.class);
 *   }
 * }</code></pre>
 *
 * With both options, the {@code Optional<Renamer>} will be present and supply the ReplacingRenamer.
 *
 * <p>Default values can be supplied using:
 *
 * <pre><code>
 * public class FrameworkModule extends AbstractModule {
 *   protected void configure() {
 *     OptionalBinder.newOptionalBinder(binder(), Key.get(String.class, LookupUrl.class))
 *         .setDefault().toInstance(DEFAULT_LOOKUP_URL);
 *   }
 * }</code></pre>
 *
 * With the above module, code can inject an {@code @LookupUrl String} and it will supply the
 * DEFAULT_LOOKUP_URL. A user can change this value by binding
 *
 * <pre><code>
 * public class UserLookupModule extends AbstractModule {
 *   protected void configure() {
 *     OptionalBinder.newOptionalBinder(binder(), Key.get(String.class, LookupUrl.class))
 *         .setBinding().toInstance(CUSTOM_LOOKUP_URL);
 *   }
 * }</code></pre>
 *
 * ... which will override the default value.
 *
 * <p>If one module uses setDefault the only way to override the default is to use setBinding. It is
 * an error for a user to specify the binding without using OptionalBinder if setDefault or
 * setBinding are called. For example,
 *
 * <pre><code>
 * public class FrameworkModule extends AbstractModule {
 *   protected void configure() {
 *     OptionalBinder.newOptionalBinder(binder(), Key.get(String.class, LookupUrl.class))
 *         .setDefault().toInstance(DEFAULT_LOOKUP_URL);
 *   }
 * }
 * public class UserLookupModule extends AbstractModule {
 *   protected void configure() {
 *     bind(Key.get(String.class, LookupUrl.class)).toInstance(CUSTOM_LOOKUP_URL);
 *   }
 * }</code></pre>
 *
 * ... would generate an error, because both the framework and the user are trying to bind
 * {@code @LookupUrl String}.
 *
 * @author sameb@google.com (Sam Berlin)
 * @since 4.0
 */
public class OptionalBinder<T> {
  // This class is non-final due to users mocking this in tests :(

  public static <T> OptionalBinder<T> newOptionalBinder(Binder binder, Class<T> type) {
    return new OptionalBinder<T>(
        newRealOptionalBinder(binder.skipSources(OptionalBinder.class), Key.get(type)));
  }

  public static <T> OptionalBinder<T> newOptionalBinder(Binder binder, TypeLiteral<T> type) {
    return new OptionalBinder<T>(
        newRealOptionalBinder(binder.skipSources(OptionalBinder.class), Key.get(type)));
  }

  public static <T> OptionalBinder<T> newOptionalBinder(Binder binder, Key<T> type) {
    return new OptionalBinder<T>(
        newRealOptionalBinder(binder.skipSources(OptionalBinder.class), type));
  }

  private final RealOptionalBinder<T> delegate;

  private OptionalBinder(RealOptionalBinder<T> delegate) {
    this.delegate = delegate;
  }

  /**
   * Returns a binding builder used to set the default value that will be injected. The binding set
   * by this method will be ignored if {@link #setBinding} is called.
   *
   * <p>It is an error to call this method without also calling one of the {@code to} methods on the
   * returned binding builder.
   */
  public LinkedBindingBuilder<T> setDefault() {
    return delegate.setDefault();
  }

  /**
   * Returns a binding builder used to set the actual value that will be injected. This overrides
   * any binding set by {@link #setDefault}.
   *
   * <p>It is an error to call this method without also calling one of the {@code to} methods on the
   * returned binding builder.
   */
  public LinkedBindingBuilder<T> setBinding() {
    return delegate.setBinding();
  }

  // Some tests depend on equals/hashCode behavior of OptionalBinder

  @Override
  public boolean equals(Object obj) {
    if (obj instanceof OptionalBinder) {
      return delegate.equals(((OptionalBinder<?>) obj).delegate);
    }
    return false;
  }

  @Override
  public int hashCode() {
    return delegate.hashCode();
  }
}