01: /**
02: * Copyright (C) 2006 Google Inc.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
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: */package com.bm.ejb3guice.inject;
16:
17: /**
18: * Simply, any object capable of providing instances of type {@code T}.
19: * Providers are used in numerous ways by the Guice framework:
20: *
21: * <ul>
22: * <li>When the default means for obtaining instances (an injectable or
23: * parameterless constructor) is insufficient for a particular binding, the
24: * module can specify a custom {@code Provider} instead, to control exactly how
25: * Guice creates or obtains instances for the binding.
26: *
27: * <li>An implementation class may always choose to have a {@code Provider<T>}
28: * instance injected, rather than having a {@code T} injected directly. This
29: * may give you access to multiple instances, instances you wish to safely
30: * mutate and discard, instances which are out of scope (e.g. using a
31: * {@code @RequestScoped} object from within a {@code @SessionScoped} object),
32: * or instances you don't want to initialize until they are absolutely needed.
33: *
34: * <li>A custom {@link Scope} is implemented as a decorator of
35: * {@code Provider<T>}, which decides when to delegate to the backing provider
36: * and when to provide the instance some other way.
37: *
38: * <li>The {@link Injector} offers access to the {@code Provider<T>} it uses
39: * to fulfill requests for a given key, via the {@link Injector#getProvider}
40: * methods.
41: * </ul>
42: *
43: * @param <T> the type of object this provider provides
44: *
45: * @author crazybob@google.com (Bob Lee)
46: */
47: public interface Provider<T> {
48:
49: /**
50: * Provides an instance of {@code T}. Must never return {@code null}.
51: *
52: * @throws OutOfScopeException when an attempt is made to access a scoped
53: * object while the scope in question is not currently active
54: */
55: T get();
56: }
|