1 /** 2 * Copyright (C) 2006 Google Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.inject; 18 19 /** 20 * An object capable of providing instances of type {@code T}. Providers are used in numerous ways 21 * by Guice: 22 * 23 * <ul> 24 * <li>When the default means for obtaining instances (an injectable or parameterless constructor) 25 * is insufficient for a particular binding, the module can specify a custom {@code Provider} 26 * instead, to control exactly how Guice creates or obtains instances for the binding. 27 * 28 * <li>An implementation class may always choose to have a {@code Provider<T>} instance injected, 29 * rather than having a {@code T} injected directly. This may give you access to multiple 30 * instances, instances you wish to safely mutate and discard, instances which are out of scope 31 * (e.g. using a {@code @RequestScoped} object from within a {@code @SessionScoped} object), or 32 * instances that will be initialized lazily. 33 * 34 * <li>A custom {@link Scope} is implemented as a decorator of {@code Provider<T>}, which decides 35 * when to delegate to the backing provider and when to provide the instance some other way. 36 * 37 * <li>The {@link Injector} offers access to the {@code Provider<T>} it uses to fulfill requests 38 * for a given key, via the {@link Injector#getProvider} methods. 39 * </ul> 40 * 41 * @param <T> the type of object this provides 42 * 43 * @author crazybob (at) google.com (Bob Lee) 44 */ 45 public interface Provider<T> extends javax.inject.Provider<T> { 46 47 /** 48 * Provides an instance of {@code T}. Must never return {@code null}. 49 * 50 * @throws OutOfScopeException when an attempt is made to access a scoped object while the scope 51 * in question is not currently active 52 * @throws ProvisionException if an instance cannot be provided. Such exceptions include messages 53 * and throwables to describe why provision failed. 54 */ 55 T get(); 56 } 57
