*/
package org.wamblee.inject;
-import java.util.ServiceLoader;
/**
* initialize fields of derived classes to null as these will override the
* initializations of this base class.
*
- * Use this by subclassing through {@link #Injectable()).
- *
- * To use this class, the {@link ServiceLoader} mechanism must be used to locate
- * a {@link InjectorFactory}. The first implementation that is found will be
- * used for injection.
+ * This class uses {@link InjectorFactoryBuilder} to obtain an implementation of
+ * a {@link InjectorFactory} to use.
*
* @author Erik Brakkee
*/
/**
* Constructs an empty cache.
*
- * @param aMgr
- * Bean manager.
+ * @param aInjectorFactory Injector factory to create Injectors.
*/
public InjectorCache(InjectorFactory aInjectorFactory) {
injectorFactory = aInjectorFactory;
/**
- * Injector factory used. This creates an injector that is appropriate for a certain class.
- * May be subclassed for testing or other advanced usage (even replacing CDI with another
- * injection framework).
+ * The injector factory is responsible for creating injectors for a given class.
+ * This must be implemneted to interface to specific dependency injection frameworks or for
+ * testing.
*
- * Implementations of this calss must have a default no-arg constructor.
+ * Implementations of this class must have a default no-arg constructor to be usable by
+ * {@link InjectorFactoryBuilder}.
*
* @author Erik Brakkee
*/
import java.util.ServiceLoader;
/**
- * Utility for obtaining an implementation of the injector factory using
+ * Utility for obtaining an implementation of the {@link InjectorFactory} using
* {@link ServiceLoader}.
*
* @author Erik Brakkee
*/
package org.wamblee.inject;
-import java.util.ServiceLoader;
-
/**
- * Singleton injector access. This should be used as main entry point for
- * injection. A different {@link InjectorFactory} can be plugged in for testing.
+ * The main entry point for programmatic dependency injection. A different
+ * {@link InjectorFactory} can be plugged in for testing.
*
- * Given the following class:
- * <pre>
- * class Pojo {
- * @EJB
- * private Service service;
+ * <p>
+ * Given the following class:
+ * </p>
+ * <pre>
+ * class Pojo {
+ * @EJB
+ * private Service service;
*
- * ...
- * }
+ * ...
+ * }
* </pre>
- * injecting the EJB into a POJO using Contexts and Dependency Injection is accomplished as follows:
+ *
+ * injecting the EJB into a POJO is accomplished as follows:
+ *
* <pre>
- * Pojo pojo = new Pojo();
- * SimpleInjector injector = new SimpleInjector(new CdiInjectorFactory());
- * injector.inject(pojo);
+ * Pojo pojo = new Pojo();
+ * SimpleInjector injector = new SimpleInjector(InjectorFactoryBuilder
+ * .getInjectorFactory());
+ * injector.inject(pojo);
* </pre>
*
- * Note that it is recommended to cache the injector because the injector does caching
- * of the types that it injects into. Caching the injector makes sure that a class is not
- * analysed again for annotation every time injection is used.
+ * Of course, the above example assumes the the injector understands the
+ * @EJB annotation (which of course CDI does).
*
- * The {@link InjectorFactory} to be used can also be found using a {@link ServiceLoader} discovery
- * mechanism as provided by {@link InjectorFactoryBuilder}.
+ * The <code>SimpleInjector</code> should be cached. This is because the
+ * <code>SimpleInjector</code> caches the {@link Injector} objects that it uses
+ * internally for performance. This is done because creation of these internal
+ * <code>Injector</code> objects may be costly. Caching the simple injector makes sure
+ * that a class is not analysed again for annotations every time injection is
+ * used.
+ *
+ * For more advanced cases, the injector factory can also be directly
+ * constructed instead of being obtained through the
+ * {@link InjectorFactoryBuilder}.
*
* @author Erik Brakkee
*/
private InjectorCache cache;
/**
- * Constructs the injector.
- * @param aFactory Factory to use.
+ * Constructs the injector.
+ *
+ * @param aFactory
+ * Factory to use.
*/
- public SimpleInjector(InjectorFactory aFactory) {
+ public SimpleInjector(InjectorFactory aFactory) {
cache = new InjectorCache(aFactory);
}
-
+
/**
* Injects into a given object.
*
* limitations under the License.
*/
/**
- * This package provides a simple general framework for dependency injection.
+ * This package provides a mini-framework for interfacing to existing dependency injection
+ * mechanisms. This package does not provide dependency injection, but implementations are expected to
+ * implement it, usually by delegating to an existing dependency injection framework. The interfaces in this
+ * package provide independence on the actual framework chosen and also allow for better testability.
+ *
+ * <h2>Users of the package</h2>
+ *
+ * <p>Users of this package will typically use: </p>
+ * <ul>
+ * <li> <code>SimpleInjector</code>: This is the class used to perform injection of dependencies into
+ * a given object. </li>
+ * <li> <code>Injectable</code>: By subclassing this class, the classes automatically get their
+ * dependencies injected at construction. </li>
+ * <li> <code>InjectorFactoryBuilder</code>: To get an injector factory reference for use in the
+ * <code>SimpleInjector</code>
+ * </ul>
+ *
+ * <h2>Implementors of the package</h2>
+ *
+ * <p>Of interest to implementations of this package integrating with dependency injection frameworks are: </p>
* <ul>
- * <li> <code>Injector</code>: The main interface is the {@link Injector}, by which injection is done.</li>
+ * <li> <code>Injector</code>: The main interface to be implemented is the {@link Injector}, by which injection is done.</li>
* <li> <code>InjectorFactory</code>: Injectors are created by an implementation of the {@link InjectorFactory} which
* creates injectors based on the class.</li>
- * <li> <code>InjectorFactoryBuilder</code>: To obtain an <code>InjectorFactory</code>,
- * either create one explicitly, or use {@link InjectorFactoryBuilder} to obtain
- * one automatically (preferred). The last method uses {@link java.util.ServiceLoader}
- * to find the injectorfactory to use.
+ * <li> <code>InjectorFactoryBuilder</code>: Implementations must make their <code>InjectorFactory</code>
+ * available through the <code>ServiceLoader</code> mechanism.
* </li>
* </ul>
*
+ * <p>Class overview</p>
* <img src="doc-files/Class_Diagram__overview.png"/>
- * <p>
- * Note that this package does not contain implementations of the injectors. For that, a separate
- * package must be used (e.g. for Contexts and Dependency Injection).
- * </p>
- *
- * <p>
- * Implementations of this package must provide an implementation of the {@link InjectorFactory} and
- * must make this implementation discoverable through the {@link java.util.ServiceLoader} mechanism.
- * </p>
*
*/
package org.wamblee.inject;
git://wamblee.org / utils / commitdiff