001: /**
002: * Copyright (C) 2006 Google Inc.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */package com.bm.ejb3guice.inject;
016:
017: import com.bm.ejb3guice.introspect.Resolver;
018:
019: import java.util.List;
020: import java.util.Map;
021:
022: /**
023: * Fulfills requests for the object instances that make up your application,
024: * always ensuring that these instances are properly injected before they are
025: * returned. The {@code Injector} is the heart of the Guice framework,
026: * although you don't typically interact with it directly very often. This
027: * "behind-the-scenes" operation is what distinguishes the dependency
028: * injection pattern from its cousin, service locator.
029: *
030: * <p>The {@code Injector} API has a few additional features: it allows
031: * pre-constructed instances to have their fields and methods injected and
032: * offers programmatic introspection to support tool development.
033: *
034: * <p>Contains several default bindings:
035: *
036: * <ul>
037: * <li>This {@link Injector} instance itself
038: * <li>A {@code Provider<T>} for each binding of type {@code T}
039: * <li>The {@link java.util.logging.Logger} for the class being injected
040: * <li>The {@link Stage} in which the Injector was created
041: * </ul>
042: *
043: * Injectors are created using the facade class {@link Ejb3Guice}.
044: *
045: * @author crazybob@google.com (Bob Lee)
046: */
047: public interface Injector {
048:
049: /**
050: * Injects dependencies into the fields and methods of an existing object.
051: * Ignores the presence or absence of an injectable constructor.
052: *
053: * <p>Whenever Guice creates an instance, it performs this injection
054: * automatically (after first performing constructor injection), so if you're
055: * able to let Guice create all your objects for you, you'll never need to
056: * use this method.
057: */
058: void injectMembers(Object o);
059:
060: /**
061: * Gets all explicit bindings. This method is part of the Injector
062: * Introspection API and is primarily intended for use by tools.
063: */
064: Map<Key<?>, Binding<?>> getBindings();
065:
066: /**
067: * Gets a binding for the given key, or null if no binding for this key is
068: * found. Note that if this key references an implementation class that can
069: * be implicitly bound, this method may return null, but may later return the
070: * implicit binding after it has been loaded. This method is part of the
071: * Injector Introspection API and is primarily intended for use by tools.
072: */
073: <T> Binding<T> getBinding(Key<T> key);
074:
075: /**
076: * Finds all bindings to the given type. This method is part of the Injector
077: * Introspection API and is primarily intended for use by tools.
078: */
079: <T> List<Binding<T>> findBindingsByType(TypeLiteral<T> type);
080:
081: /**
082: * Returns the provider used to obtain instances for the given injection key.
083: * When feasible, it's generally preferable to avoid using this method, in
084: * favor of having Guice inject your dependencies ahead of time.
085: */
086: <T> Provider<T> getProvider(Key<T> key);
087:
088: /**
089: * Returns the provider used to obtain instances for the given injection key.
090: * When feasible, it's generally preferable to avoid using this method, in
091: * favor of having Guice inject your dependencies ahead of time.
092: */
093: <T> Provider<T> getProvider(Class<T> type);
094:
095: /**
096: * Returns the appropriate instance for the given injection key; equivalent to
097: * {@code getProvider(key).get()}. When feasible, it's generally preferable to
098: * avoid using this method, in favor of having Guice inject your dependencies
099: * ahead of time.
100: */
101: <T> T getInstance(Key<T> key);
102:
103: /**
104: * Returns the appropriate instance for the given type; equivalent to
105: * {@code getProvider(type).get()}. When feasible, it's generally preferable
106: * to avoid using this method, in favor of having Guice inject your
107: * dependencies ahead of time.
108: */
109: <T> T getInstance(Class<T> type);
110:
111: /**
112: * Returns the resolver used by this injector to resolve injection requests.
113: * This method is part of the Injector Introspection API and is primarily
114: * intended for use by tools.
115: */
116: Resolver getResolver();
117: }
|