diff options
27 files changed, 108 insertions, 167 deletions
diff --git a/atinject.ipr b/atinject.ipr index a1aa219..bc9f3d5 100644 --- a/atinject.ipr +++ b/atinject.ipr @@ -30,6 +30,9 @@ <entry name="?*.ftl" /> </wildcardResourcePatterns> </component> + <component name="CopyrightManager" default=""> + <module2copyright /> + </component> <component name="DependencyValidationManager"> <option name="SKIP_IMPORT_STATEMENTS" value="false" /> </component> diff --git a/javadoc/allclasses-frame.html b/javadoc/allclasses-frame.html index 50a11fa..1c8e36b 100644 --- a/javadoc/allclasses-frame.html +++ b/javadoc/allclasses-frame.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> All Classes </TITLE> diff --git a/javadoc/allclasses-noframe.html b/javadoc/allclasses-noframe.html index 7f8094c..4e10083 100644 --- a/javadoc/allclasses-noframe.html +++ b/javadoc/allclasses-noframe.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> All Classes </TITLE> diff --git a/javadoc/constant-values.html b/javadoc/constant-values.html index 2367f70..c02a31a 100644 --- a/javadoc/constant-values.html +++ b/javadoc/constant-values.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> Constant Field Values </TITLE> diff --git a/javadoc/deprecated-list.html b/javadoc/deprecated-list.html index 722ce8c..66f4730 100644 --- a/javadoc/deprecated-list.html +++ b/javadoc/deprecated-list.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> Deprecated List </TITLE> diff --git a/javadoc/help-doc.html b/javadoc/help-doc.html index 71e08d0..6a590d4 100644 --- a/javadoc/help-doc.html +++ b/javadoc/help-doc.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> API Help </TITLE> diff --git a/javadoc/index-files/index-1.html b/javadoc/index-files/index-1.html index 4c10f96..7433a9c 100644 --- a/javadoc/index-files/index-1.html +++ b/javadoc/index-files/index-1.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> G-Index </TITLE> diff --git a/javadoc/index-files/index-2.html b/javadoc/index-files/index-2.html index cd0368b..a98190a 100644 --- a/javadoc/index-files/index-2.html +++ b/javadoc/index-files/index-2.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> I-Index </TITLE> diff --git a/javadoc/index-files/index-3.html b/javadoc/index-files/index-3.html index fe9bfc8..ec69d61 100644 --- a/javadoc/index-files/index-3.html +++ b/javadoc/index-files/index-3.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> J-Index </TITLE> diff --git a/javadoc/index-files/index-4.html b/javadoc/index-files/index-4.html index 374efe3..c9f41db 100644 --- a/javadoc/index-files/index-4.html +++ b/javadoc/index-files/index-4.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> N-Index </TITLE> diff --git a/javadoc/index-files/index-5.html b/javadoc/index-files/index-5.html index fbbedc1..ac04497 100644 --- a/javadoc/index-files/index-5.html +++ b/javadoc/index-files/index-5.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> P-Index </TITLE> diff --git a/javadoc/index-files/index-6.html b/javadoc/index-files/index-6.html index 09615f8..e9a4fb4 100644 --- a/javadoc/index-files/index-6.html +++ b/javadoc/index-files/index-6.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> Q-Index </TITLE> diff --git a/javadoc/index-files/index-7.html b/javadoc/index-files/index-7.html index f43d870..c08e708 100644 --- a/javadoc/index-files/index-7.html +++ b/javadoc/index-files/index-7.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> S-Index </TITLE> diff --git a/javadoc/index.html b/javadoc/index.html index 92c5514..f0792ca 100644 --- a/javadoc/index.html +++ b/javadoc/index.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc on Tue Apr 28 17:34:50 PDT 2009--> +<!-- Generated by javadoc on Tue Jun 23 17:21:19 CDT 2009--> <TITLE> Generated Documentation (Untitled) </TITLE> diff --git a/javadoc/javax/inject/Inject.html b/javadoc/javax/inject/Inject.html index 17b52f8..64b5ecb 100644 --- a/javadoc/javax/inject/Inject.html +++ b/javadoc/javax/inject/Inject.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> Inject </TITLE> @@ -71,9 +71,9 @@ function windowTitle() </TR> <TR> <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> - SUMMARY: REQUIRED | <A HREF="#annotation_type_optional_element_summary">OPTIONAL</A></FONT></TD> + SUMMARY: REQUIRED | OPTIONAL</FONT></TD> <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> -DETAIL: <A HREF="#annotation_type_element_detail">ELEMENT</A></FONT></TD> +DETAIL: ELEMENT</FONT></TD> </TR> </TABLE> <A NAME="skip-navbar_top"></A> @@ -142,17 +142,21 @@ Identifies injectable constructors, methods, and fields. Applies to static <li>are annotated with <code>@Inject</code>.</li> <li>are not abstract.</li> <li>do not declare type parameters of their own.</li> - <li>return <code>void</code>.</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</code> return types are allowed to support use of the method in + other contexts (builder-style method chaining, for example). + <p>For example: <pre> @@ -173,10 +177,31 @@ Identifies injectable constructors, methods, and fields. Applies to static that overrides a method annotated with <code>@Inject</code> will not be injected. - <p>Injection of members annotated with <code>@Inject</code> is required by - default. This behavior can be overridden by setting <A HREF="../../javax/inject/Inject.html#optional()"><CODE>optional</CODE></A> equal to <code>true</code>. + <p>Injection of members annotated with <code>@Inject</code> is required. + + <h3>Qualifiers</h3> + + <p>A <A HREF="../../javax/inject/Qualifier.html" title="annotation in javax.inject">qualifier</A> 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</code>, no more + than one qualifier should annotate a single field or parameter. The + qualifiers are bold in the following example: + + <pre> + public class Car { + @Inject private <b>@Leather</b> Provider<Seat> seatProvider; + + @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>Detecting and resolving circular dependencies is left as an exercize for + <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: @@ -208,66 +233,10 @@ Identifies injectable constructors, methods, and fields. Applies to static <DL> <DT><B>See Also:</B><DD><A HREF="../../javax/inject/Qualifier.html" title="annotation in javax.inject"><CODE>@Qualifier</CODE></A>, <A HREF="../../javax/inject/Provider.html" title="interface in javax.inject"><CODE>Provider</CODE></A></DL> -<HR> <P> -<!-- =========== ANNOTATION TYPE OPTIONAL MEMBER SUMMARY =========== --> -<A NAME="annotation_type_optional_element_summary"><!-- --></A> -<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> -<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> -<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> -<B>Optional Element Summary</B></FONT></TH> -</TR> -<TR BGCOLOR="white" CLASS="TableRowColor"> -<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> -<CODE> boolean</CODE></FONT></TD> -<TD><CODE><B><A HREF="../../javax/inject/Inject.html#optional()">optional</A></B></CODE> - -<BR> - Whether or not injection is optional.</TD> -</TR> -</TABLE> - <P> -<A NAME="optional()"><!-- --></A><H3> -optional</H3> -<PRE> -public abstract boolean <B>optional</B></PRE> -<DL> -<DD>Whether or not injection is optional. If <code>true</code>, 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> - @Inject(optional=true) Gps gps;</pre> - - <p>If a Gps isn't available at all, the injector will simply not set the - <code>gps</code> field. If a Gps is available but an algorithm it depends - upon can't be found, the injector will generate an error. -<P> -<DD><DL> -</DL> -</DD> -<DD><DL> -</DL> -<DL> -<DT><B>Default:</B><DD>false</DD> -</DL> -</DL> <!-- ========= END OF CLASS DATA ========= --> <HR> @@ -318,9 +287,9 @@ public abstract boolean <B>optional</B></PRE> </TR> <TR> <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> - SUMMARY: REQUIRED | <A HREF="#annotation_type_optional_element_summary">OPTIONAL</A></FONT></TD> + SUMMARY: REQUIRED | OPTIONAL</FONT></TD> <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> -DETAIL: <A HREF="#annotation_type_element_detail">ELEMENT</A></FONT></TD> +DETAIL: ELEMENT</FONT></TD> </TR> </TABLE> <A NAME="skip-navbar_bottom"></A> diff --git a/javadoc/javax/inject/Named.html b/javadoc/javax/inject/Named.html index add733b..bd78e93 100644 --- a/javadoc/javax/inject/Named.html +++ b/javadoc/javax/inject/Named.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> Named </TITLE> diff --git a/javadoc/javax/inject/Provider.html b/javadoc/javax/inject/Provider.html index af72046..3ad48ac 100644 --- a/javadoc/javax/inject/Provider.html +++ b/javadoc/javax/inject/Provider.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> Provider </TITLE> diff --git a/javadoc/javax/inject/Qualifier.html b/javadoc/javax/inject/Qualifier.html index 5e20a25..281fec8 100644 --- a/javadoc/javax/inject/Qualifier.html +++ b/javadoc/javax/inject/Qualifier.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> Qualifier </TITLE> @@ -95,25 +95,9 @@ Annotation Type Qualifier</H2> </PRE> <P> -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 { - @Inject private <b>@Leather</b> Provider<Seat> seatProvider; - - @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>, <code>@Retention(RUNTIME)</code>, and typically <code>@Documented</code>.</li> diff --git a/javadoc/javax/inject/Scope.html b/javadoc/javax/inject/Scope.html index 3df56a6..5fcf305 100644 --- a/javadoc/javax/inject/Scope.html +++ b/javadoc/javax/inject/Scope.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> Scope </TITLE> diff --git a/javadoc/javax/inject/Singleton.html b/javadoc/javax/inject/Singleton.html index f8bb89b..210de4d 100644 --- a/javadoc/javax/inject/Singleton.html +++ b/javadoc/javax/inject/Singleton.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> Singleton </TITLE> diff --git a/javadoc/javax/inject/package-frame.html b/javadoc/javax/inject/package-frame.html index 0a3b4bc..1a00f06 100644 --- a/javadoc/javax/inject/package-frame.html +++ b/javadoc/javax/inject/package-frame.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> javax.inject </TITLE> diff --git a/javadoc/javax/inject/package-summary.html b/javadoc/javax/inject/package-summary.html index a028de8..57ed096 100644 --- a/javadoc/javax/inject/package-summary.html +++ b/javadoc/javax/inject/package-summary.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> javax.inject </TITLE> diff --git a/javadoc/javax/inject/package-tree.html b/javadoc/javax/inject/package-tree.html index dd2ef34..82ead16 100644 --- a/javadoc/javax/inject/package-tree.html +++ b/javadoc/javax/inject/package-tree.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> javax.inject Class Hierarchy </TITLE> diff --git a/javadoc/overview-tree.html b/javadoc/overview-tree.html index 7aa5a55..cdcd630 100644 --- a/javadoc/overview-tree.html +++ b/javadoc/overview-tree.html @@ -2,7 +2,7 @@ <!--NewPage--> <HTML> <HEAD> -<!-- Generated by javadoc (build 1.5.0_13) on Tue Apr 28 17:34:50 PDT 2009 --> +<!-- Generated by javadoc (build 1.5.0_16) on Tue Jun 23 17:21:19 CDT 2009 --> <TITLE> Class Hierarchy </TITLE> 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 { + * @Inject private <b>@Leather</b> Provider<Seat> seatProvider; * - * <p>Detecting and resolving circular dependencies is left as an exercize for + * @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> - * @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 { - * @Inject private <b>@Leather</b> Provider<Seat> seatProvider; - * - * @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> |