• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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@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    */
get()55   T get();
56 }
57