improvements to the documentation.
authorErik Brakkee <erik@brakkee.org>
Thu, 15 Jul 2010 22:10:16 +0000 (22:10 +0000)
committerErik Brakkee <erik@brakkee.org>
Thu, 15 Jul 2010 22:10:16 +0000 (22:10 +0000)
support/inject/src/main/java/org/wamblee/inject/Injectable.java
support/inject/src/main/java/org/wamblee/inject/InjectorCache.java
support/inject/src/main/java/org/wamblee/inject/InjectorFactory.java
support/inject/src/main/java/org/wamblee/inject/InjectorFactoryBuilder.java
support/inject/src/main/java/org/wamblee/inject/SimpleInjector.java
support/inject/src/main/java/org/wamblee/inject/package-info.java

index 0c881d9b104d50a796a815d13f0bd5ce955ee309..4f55cc35e2db8cc05da4766bde0424c794629810 100644 (file)
@@ -15,7 +15,6 @@
  */
 package org.wamblee.inject;
 
-import java.util.ServiceLoader;
 
 
 /**
@@ -23,11 +22,8 @@ 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
  */
index 9bf6e2df28a6c0bbeb7c2bbd052576933636eb13..3e272f5fb35bd753088adab041195624e5c9584a 100644 (file)
@@ -33,8 +33,7 @@ public class InjectorCache {
     /**
      * Constructs an empty cache.
      * 
-     * @param aMgr
-     *            Bean manager.
+     * @param aInjectorFactory Injector factory to create Injectors. 
      */
     public InjectorCache(InjectorFactory aInjectorFactory) {
         injectorFactory = aInjectorFactory;
index 84f7a66bb5d4e1645370d5c41b6dd88c7a136742..9f2dfe2283ec70039d431ed6b3d6a4d443ebf500 100644 (file)
@@ -17,11 +17,12 @@ package org.wamblee.inject;
 
 
 /**
- * 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
  */
index d6005005602ff4f8e8abcf576e966966bec59919..d8190919db6a0ca2f2e0163b541521b3edf55a04 100644 (file)
@@ -19,7 +19,7 @@ import java.util.NoSuchElementException;
 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
index 61bb55608b33839d8012e42b5006de2c90218b68..9e83064c98cbe5e8f7f5007e94e0fb14ff751b82 100644 (file)
  */
 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 {
- *   &#064;EJB
- *   private Service service; 
+ * <p>
+ * Given the following class:
+ * </p>
+ * <pre>
+ *   class Pojo {
+ *     &#064;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
+ * &#064;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
  */
@@ -52,13 +62,15 @@ public class SimpleInjector {
     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.
      * 
index 3cc9841efa66b9496980dd78cf18cd34f4051f12..c07c8ab89a81d11168956f4f36b7c956eeddf534 100644 (file)
  * 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;