Provider.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;

/**
 * Simply, any object capable of providing instances of type {@code T}.
 * Providers are used in numerous ways by the Guice framework:
 *
 * <ul>
 * <li>When the default means for obtaining instances (an injectable or
 * parameterless constructor) is insufficient for a particular binding, the
 * module can specify a custom {@code Provider} instead, to control exactly how
 * Guice creates or obtains instances for the binding.
 *
 * <li>An implementation class may always choose to have a {@code Provider<T>}
 * instance injected, rather than having a {@code T} injected directly.  This
 * may give you access to multiple instances, instances you wish to safely
 * mutate and discard, instances which are out of scope (e.g. using a
 * {@code @RequestScoped} object from within a {@code @SessionScoped} object),
 * or instances you don't want to initialize until they are absolutely needed.
 *
 * <li>A custom {@link Scope} is implemented as a decorator of
 * {@code Provider<T>}, which decides when to delegate to the backing provider
 * and when to provide the instance some other way.
 *
 * <li>The {@link Injector} offers access to the {@code Provider<T>} it uses
 * to fulfill requests for a given key, via the {@link Injector#getProvider}
 * methods.
 * </ul>
 *
 * @param <T> the type of object this provider provides
 *
 * @author crazybob@google.com (Bob Lee)
 */
public interface Provider<T> extends javax.inject.Provider<T> {

  /**
   * Provides an instance of {@code T}. Must never return {@code null}.
   *
   * @throws OutOfScopeException when an attempt is made to access a scoped
   *     object while the scope in question is not currently active
   */
  T get();
}