From: erik Date: Thu, 15 Jul 2010 22:10:16 +0000 (+0000) Subject: improvements to the documentation. X-Git-Tag: wamblee-utils-0.3~66 X-Git-Url: http://wamblee.org/gitweb/?a=commitdiff_plain;h=466df0c4c373fe3d86a851fa4adbf72d015a0225;p=utils improvements to the documentation. --- diff --git a/support/inject/src/main/java/org/wamblee/inject/Injectable.java b/support/inject/src/main/java/org/wamblee/inject/Injectable.java index 0c881d9b..4f55cc35 100644 --- a/support/inject/src/main/java/org/wamblee/inject/Injectable.java +++ b/support/inject/src/main/java/org/wamblee/inject/Injectable.java @@ -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 */ diff --git a/support/inject/src/main/java/org/wamblee/inject/InjectorCache.java b/support/inject/src/main/java/org/wamblee/inject/InjectorCache.java index 9bf6e2df..3e272f5f 100644 --- a/support/inject/src/main/java/org/wamblee/inject/InjectorCache.java +++ b/support/inject/src/main/java/org/wamblee/inject/InjectorCache.java @@ -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; diff --git a/support/inject/src/main/java/org/wamblee/inject/InjectorFactory.java b/support/inject/src/main/java/org/wamblee/inject/InjectorFactory.java index 84f7a66b..9f2dfe22 100644 --- a/support/inject/src/main/java/org/wamblee/inject/InjectorFactory.java +++ b/support/inject/src/main/java/org/wamblee/inject/InjectorFactory.java @@ -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 */ diff --git a/support/inject/src/main/java/org/wamblee/inject/InjectorFactoryBuilder.java b/support/inject/src/main/java/org/wamblee/inject/InjectorFactoryBuilder.java index d6005005..d8190919 100644 --- a/support/inject/src/main/java/org/wamblee/inject/InjectorFactoryBuilder.java +++ b/support/inject/src/main/java/org/wamblee/inject/InjectorFactoryBuilder.java @@ -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 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 61bb5560..9e83064c 100644 --- 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: - * 
 
- * class Pojo {
- *   @EJB
- *   private Service service; 
+ * 

+ * Given the following class:
+ * 

+ * 
+ *   class Pojo {
+ *     @EJB
+ *     private Service service; 
  *   
- *   ...
- * }
+ *     ...
+ *   }
  * 

- * 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:
+ * 
  * 
- *   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);
  * 

  * 
- * 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 SimpleInjector should be cached. This is because the
+ * SimpleInjector caches the {@link Injector} objects that it uses
+ * internally for performance. This is done because creation of these internal
+ * Injector 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.
      * 
diff --git a/support/inject/src/main/java/org/wamblee/inject/package-info.java b/support/inject/src/main/java/org/wamblee/inject/package-info.java
index 3cc9841e..c07c8ab8 100644
--- a/support/inject/src/main/java/org/wamblee/inject/package-info.java
+++ b/support/inject/src/main/java/org/wamblee/inject/package-info.java
@@ -14,28 +14,37 @@
  * 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. 
+ * 
+ * 
Users of the package

+ * 
+ * 
Users of this package will typically use: 

+ * 
+ * 
+ * 
Implementors of the package

+ * 
+ * 
Of interest to implementations of this package integrating with dependency injection frameworks are: 

  * 
  * 
+ * 
Class overview

  * 
- * 

- * 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). 
- * 

- * 
- * 

- * 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. 
- * 

  *
  */
 package org.wamblee.inject;