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 * <li>An implementation class may always choose to have a {@code Provider<T>} instance injected, 28 * rather than having a {@code T} injected directly. This may give you access to multiple 29 * instances, instances you wish to safely mutate and discard, instances which are out of scope 30 * (e.g. using a {@code @RequestScoped} object from within a {@code @SessionScoped} object), or 31 * instances that will be initialized lazily. 32 * <li>A custom {@link Scope} is implemented as a decorator of {@code Provider<T>}, which decides 33 * when to delegate to the backing provider and when to provide the instance some other way. 34 * <li>The {@link Injector} offers access to the {@code Provider<T>} it uses to fulfill requests for 35 * a given key, via the {@link Injector#getProvider} methods. 36 * </ul> 37 * 38 * @param <T> the type of object this provides 39 * @author crazybob@google.com (Bob Lee) 40 */ 41 public interface Provider<T> extends javax.inject.Provider<T> { 42 43 /** 44 * Provides an instance of {@code T}. 45 * 46 * @throws OutOfScopeException when an attempt is made to access a scoped object while the scope 47 * in question is not currently active 48 * @throws ProvisionException if an instance cannot be provided. Such exceptions include messages 49 * and throwables to describe why provision failed. 50 */ 51 @Override get()52 T get(); 53 } 54