Added a note about exceptions to Provider's docs. Noted that Provider is typically implemented by an injector. Specified that instances returned by Provider.get() are fully constructed and

injected. Allowed methods to return types other than void. Added note about qualifiers to @Inject doc. Removed "optional" attribute from @Inject. Limited the scope of some qualifier restrictions so they only apply to @Inject methods and not qualifiers in general.



git-svn-id: https://atinject.googlecode.com/svn/trunk@4 3bc8319c-20ab-11de-9edc-3f40a397ab60

3 files changed, 46 insertions, 61 deletions

diff --git a/src/javax/inject/Inject.java b/src/javax/inject/Inject.java
index 1509d21..e8bdfb4 100644
--- a/src/javax/inject/Inject.java
+++ b/src/javax/inject/Inject.java
@@ -9,7 +9,7 @@ import static java.lang.annotation.ElementType.CONSTRUCTOR;
 import static java.lang.annotation.ElementType.FIELD;
 
 /**
- * Identifies injectable constructors, methods, and fields. Applies to static
+ * Identifies injectable constructors, methods, and fields. May apply to static
  * as well as instance members. An injectable member may have any access
  * modifier (private, package-private, protected, public). Constructors are
  * injected first, followed by fields, and then methods. Fields and methods
@@ -56,17 +56,21 @@ import static java.lang.annotation.ElementType.FIELD;
  *   <li>are annotated with {@code @Inject}.</li>
  *   <li>are not abstract.</li>
  *   <li>do not declare type parameters of their own.</li>
- *   <li>return {@code void}.</li>
+ *   <li>may return a result</li>
  *   <li>may have any otherwise valid name.</li>
  *   <li>accept zero or more dependencies as arguments.</li></ul>
  *
  * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject
  *       <i>MethodModifiers<sub>opt</sub></i>
- *       void
+ *       <i>ResultType</i>
  *       <i>Identifier</i>(<i>FormalParameterList<sub>opt</sub></i>)
  *       <i>Throws<sub>opt</sub></i>
  *       <i>MethodBody</i></blockquote></tt>
  *
+ * <p>The injector ignores the result of an injected method, but
+ * non-{@code void} return types are allowed to support use of the method in
+ * other contexts (builder-style method chaining, for example).
+ *
  * <p>For example:
  *
  * <pre>
@@ -87,11 +91,31 @@ import static java.lang.annotation.ElementType.FIELD;
  * that overrides a method annotated with {@code @Inject} will not be
  * injected.
  *
- * <p>Injection of members annotated with {@code @Inject} is required by
- * default. This behavior can be overridden by setting {@link #optional()
- * optional} equal to {@code true}.
+ * <p>Injection of members annotated with {@code @Inject} is required.
+ *
+ * <h3>Qualifiers</h3>
+ *
+ * <p>A {@linkplain Qualifier qualifier} may annotate an injectable field
+ * or parameter and, combined with the type, identify the implementation to
+ * inject. Qualifiers are optional and when used with {@code @Inject}, no more
+ * than one qualifier should annotate a single field or parameter. The
+ * qualifiers are bold in the following example:
+ *
+ * <pre>
+ *   public class Car {
+ *     &#064;Inject private <b>@Leather</b> Provider&lt;Seat> seatProvider;
  *
- * <p>Detecting and resolving circular dependencies is left as an exercize for
+ *     &#064;Inject void install(<b>@Tinted</b> Windshield windshield,
+ *         <b>@Big</b> Trunk trunk) { ... }
+ *   }</pre>
+ *
+ * <p>If one injectable method overrides another, the overriding method's
+ * parameters do not automatically inherit qualifiers from the overridden
+ * method's parameters.
+ *
+ * <h3>Circular Dependencies</h3>
+ *
+ * <p>Detecting and resolving circular dependencies is left as an exercise for
  * the injector implementation. Circular dependencies between two constructors
  * is an obvious problem, but you can also have a circular dependency between
  * injectable fields or methods:
@@ -126,32 +150,4 @@ import static java.lang.annotation.ElementType.FIELD;
 @Target({ METHOD, CONSTRUCTOR, FIELD })
 @Retention(RUNTIME)
 @Documented
-public @interface Inject {
-
-    /**
-     * Whether or not injection is optional. If {@code true}, the injector's
-     * behavior varies depending on the type of injection point:
-     *
-     * <p><ul>
-     *   <li><b>Constructors:</b> <i>Not allowed</i></li>
-     *   <li><b>Fields:</b> If a dependency matching the field can't
-     *     be found, the injector will not set the field.</li>
-     *   <li><b>Methods:</b> If a dependency matching a method parameter can't
-     *     be found, the injector will skip invoking the method entirely, even
-     *     if other arguments could be provided.</li>
-     * </ul>
-     * 
-     * <p>If an applicable dependency has been configured but the injector
-     * encounters an error while resolving the dependency (a transitive
-     * dependency could be missing, for example), the injector should generate
-     * an error, not skip the injection. For example:
-     *
-     * <pre>
-     *   &#064;Inject(optional=true) Gps gps;</pre>
-     *
-     * <p>If a Gps isn't available at all, the injector will simply not set the
-     * {@code gps} field. If a Gps is available but an algorithm it depends
-     * upon can't be found, the injector will generate an error.
-     */
-    boolean optional() default false;
-}
+public @interface Inject {}
diff --git a/src/javax/inject/Provider.java b/src/javax/inject/Provider.java
index ba1df61..ffc0878 100644
--- a/src/javax/inject/Provider.java
+++ b/src/javax/inject/Provider.java
@@ -1,9 +1,10 @@
 package javax.inject;
 
 /**
- * Provides instances of {@code T}. For any type {@code T} that can be
- * injected, you can also inject {@code Provider<T>}. Compared to injecting
- * {@code T} directly, injecting {@code Provider<T>} enables:
+ * Provides instances of {@code T}. Typically implemented by an injector. For
+ * any type {@code T} that can be injected, you can also inject
+ * {@code Provider<T>}. Compared to injecting {@code T} directly, injecting
+ * {@code Provider<T>} enables:
  *
  * <ul>
  *   <li>retrieving multiple instances.</li>
@@ -26,11 +27,15 @@ package javax.inject;
  */
 public interface Provider<T> {
 
-    // TODO: Specify OutOfScopeException (or IllegalStateException) and
-    //  ProvisionException?
-
     /**
-     * Provides an instance of {@code T}.
+     * Provides a fully-constructed and injected instance of {@code T}.
+     *
+     * @throws RuntimeException if the injector encounters an error while
+     *  providing an instance. For example, if an injectable member on
+     *  {@code T} throws an exception, the injector may wrap the exception
+     *  and throw it to the caller of {@code get()}. Callers should not try
+     *  to handle such exceptions as the behavior may vary across injector
+     *  implementations and even different configurations of the same injector.
      */
     T get();
 }
diff --git a/src/javax/inject/Qualifier.java b/src/javax/inject/Qualifier.java
index 1eab6a7..94ac3da 100644
--- a/src/javax/inject/Qualifier.java
+++ b/src/javax/inject/Qualifier.java
@@ -7,25 +7,9 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 
 /**
- * Identifies qualifier annotations. A qualifier annotates an injectable field
- * or parameter and, combined with the type, identifies the implementation to
- * inject. Qualifiers are optional and no more than one should annotate a
- * single field or parameter. The qualifiers are bold in the following
- * example:
+ * Identifies qualifier annotations. Anyone can define a new qualifier. A
+ * qualifier annotation:
  *
- * <pre>
- *   public class Car {
- *     &#064;Inject private <b>@Leather</b> Provider&lt;Seat> seatProvider;
- *
- *     &#064;Inject void install(<b>@Tinted</b> Windshield windshield,
- *         <b>@Big</b> Trunk trunk) { ... }
- *   }</pre>
- *
- * <p>If one injectable method overrides another, the overriding method's
- * parameters do not automatically inherit qualifiers from the overridden
- * method's parameters.
- *
- * <p>Anyone can define a new qualifier. A qualifier annotation:
  * <ul>
  *   <li>is annotated with {@code @Qualifier}, {@code @Retention(RUNTIME)},
  *      and typically {@code @Documented}.</li>