improvements to the documentation.

[utils] / support / inject / src / main / java / org / wamblee / inject / SimpleInjector.java

diff --git a/support/inject/src/main/java/org/wamblee/inject/SimpleInjector.java b/support/inject/src/main/java/org/wamblee/inject/SimpleInjector.java
index 61bb55608b33839d8012e42b5006de2c90218b68..9e83064c98cbe5e8f7f5007e94e0fb14ff751b82 100644 (file)
--- a/support/inject/src/main/java/org/wamblee/inject/SimpleInjector.java
+++ b/support/inject/src/main/java/org/wamblee/inject/SimpleInjector.java
@@ -15,35 +15,45 @@
  */
 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.
      *