Home | History | Annotate | Download | only in inject
      1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
      2 <!--NewPage-->
      3 <HTML>
      4 <HEAD>
      5 <!-- Generated by javadoc (build 1.5.0_16) on Mon Oct 12 16:11:19 PDT 2009 -->
      6 <TITLE>
      7 Inject
      8 </TITLE>
      9 
     10 <META NAME="keywords" CONTENT="javax.inject.Inject class">
     11 
     12 <LINK REL ="stylesheet" TYPE="text/css" HREF="../../stylesheet.css" TITLE="Style">
     13 
     14 <SCRIPT type="text/javascript">
     15 function windowTitle()
     16 {
     17     parent.document.title="Inject";
     18 }
     19 </SCRIPT>
     20 <NOSCRIPT>
     21 </NOSCRIPT>
     22 
     23 </HEAD>
     24 
     25 <BODY BGCOLOR="white" onload="windowTitle();">
     26 
     27 
     28 <!-- ========= START OF TOP NAVBAR ======= -->
     29 <A NAME="navbar_top"><!-- --></A>
     30 <A HREF="#skip-navbar_top" title="Skip navigation links"></A>
     31 <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
     32 <TR>
     33 <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
     34 <A NAME="navbar_top_firstrow"><!-- --></A>
     35 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
     36   <TR ALIGN="center" VALIGN="top">
     37   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../javax/inject/package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
     38   <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
     39   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
     40   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
     41   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
     42   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
     43   </TR>
     44 </TABLE>
     45 </TD>
     46 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
     47 </EM>
     48 </TD>
     49 </TR>
     50 
     51 <TR>
     52 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
     53 &nbsp;PREV CLASS&nbsp;
     54 &nbsp;<A HREF="../../javax/inject/Named.html" title="annotation in javax.inject"><B>NEXT CLASS</B></A></FONT></TD>
     55 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
     56   <A HREF="../../index.html?javax/inject/Inject.html" target="_top"><B>FRAMES</B></A>  &nbsp;
     57 &nbsp;<A HREF="Inject.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
     58 &nbsp;<SCRIPT type="text/javascript">
     59   <!--
     60   if(window==top) {
     61     document.writeln('<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>');
     62   }
     63   //-->
     64 </SCRIPT>
     65 <NOSCRIPT>
     66   <A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>
     67 </NOSCRIPT>
     68 
     69 
     70 </FONT></TD>
     71 </TR>
     72 <TR>
     73 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
     74   SUMMARY:&nbsp;REQUIRED&nbsp;|&nbsp;OPTIONAL</FONT></TD>
     75 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
     76 DETAIL:&nbsp;ELEMENT</FONT></TD>
     77 </TR>
     78 </TABLE>
     79 <A NAME="skip-navbar_top"></A>
     80 <!-- ========= END OF TOP NAVBAR ========= -->
     81 
     82 <HR>
     83 <!-- ======== START OF CLASS DATA ======== -->
     84 <H2>
     85 <FONT SIZE="-1">
     86 javax.inject</FONT>
     87 <BR>
     88 Annotation Type Inject</H2>
     89 <HR>
     90 <DL>
     91 <DT><PRE><FONT SIZE="-1">@Target(value={METHOD,CONSTRUCTOR,FIELD})
     92 @Retention(value=RUNTIME)
     93 @Documented
     94 </FONT>public @interface <B>Inject</B></DL>
     95 </PRE>
     96 
     97 <P>
     98 Identifies injectable constructors, methods, and fields. May apply to static
     99  as well as instance members. An injectable member may have any access
    100  modifier (private, package-private, protected, public). Constructors are
    101  injected first, followed by fields, and then methods. Fields and methods
    102  in superclasses are injected before those in subclasses. Ordering of
    103  injection among fields and among methods in the same class is not specified.
    104 
    105  <p>Injectable constructors are annotated with <code>@Inject</code> and accept
    106  zero or more dependencies as arguments. <code>@Inject</code> can apply to at most
    107  one constructor per class.
    108 
    109  <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject
    110        <i>ConstructorModifiers<sub>opt</sub></i>
    111        <i>SimpleTypeName</i>(<i>FormalParameterList<sub>opt</sub></i>)
    112        <i>Throws<sub>opt</sub></i>
    113        <i>ConstructorBody</i></blockquote></tt>
    114 
    115  <p><code>@Inject</code> is optional for public, no-argument constructors when no
    116  other constructors are present. This enables injectors to invoke default
    117  constructors.
    118 
    119  <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">
    120        @Inject<sub><i>opt</i></sub>
    121        <i>Annotations<sub>opt</sub></i>
    122        public
    123        <i>SimpleTypeName</i>()
    124        <i>Throws<sub>opt</sub></i>
    125        <i>ConstructorBody</i></blockquote></tt>
    126 
    127  <p>Injectable fields:
    128  <ul>
    129    <li>are annotated with <code>@Inject</code>.
    130    <li>are not final.
    131    <li>may have any otherwise valid name.</li></ul>
    132 
    133  <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject
    134        <i>FieldModifiers<sub>opt</sub></i>
    135        <i>Type</i>
    136        <i>VariableDeclarators</i>;</blockquote></tt>
    137 
    138  <p>Injectable methods:
    139  <ul>
    140    <li>are annotated with <code>@Inject</code>.</li>
    141    <li>are not abstract.</li>
    142    <li>do not declare type parameters of their own.</li>
    143    <li>may return a result</li>
    144    <li>may have any otherwise valid name.</li>
    145    <li>accept zero or more dependencies as arguments.</li></ul>
    146 
    147  <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject
    148        <i>MethodModifiers<sub>opt</sub></i>
    149        <i>ResultType</i>
    150        <i>Identifier</i>(<i>FormalParameterList<sub>opt</sub></i>)
    151        <i>Throws<sub>opt</sub></i>
    152        <i>MethodBody</i></blockquote></tt>
    153 
    154  <p>The injector ignores the result of an injected method, but
    155  non-<code>void</code> return types are allowed to support use of the method in
    156  other contexts (builder-style method chaining, for example).
    157 
    158  <p>Examples:
    159 
    160  <pre>
    161    public class Car {
    162      // Injectable constructor
    163      &#064;Inject public Car(Engine engine) { ... }
    164 
    165      // Injectable field
    166      &#064;Inject private Provider&lt;Seat> seatProvider;
    167 
    168      // Injectable package-private method
    169      &#064;Inject void install(Windshield windshield, Trunk trunk) { ... }
    170    }</pre>
    171 
    172  <p>A method annotated with <code>@Inject</code> that overrides another method
    173  annotated with <code>@Inject</code> will only be injected once per injection
    174  request per instance. A method with <i>no</i> <code>@Inject</code> annotation
    175  that overrides a method annotated with <code>@Inject</code> will not be
    176  injected.
    177 
    178  <p>Injection of members annotated with <code>@Inject</code> is required. While an
    179  injectable member may use any accessibility modifier (including
    180  <tt>private</tt>), platform or injector limitations (like security
    181  restrictions or lack of reflection support) might preclude injection
    182  of non-public members.
    183 
    184  <h3>Qualifiers</h3>
    185 
    186  <p>A <A HREF="../../javax/inject/Qualifier.html" title="annotation in javax.inject">qualifier</A> may annotate an injectable field
    187  or parameter and, combined with the type, identify the implementation to
    188  inject. Qualifiers are optional, and when used with <code>@Inject</code> in
    189  injector-independent classes, no more than one qualifier should annotate a
    190  single field or parameter. The qualifiers are bold in the following example:
    191 
    192  <pre>
    193    public class Car {
    194      &#064;Inject private <b>@Leather</b> Provider&lt;Seat> seatProvider;
    195 
    196      &#064;Inject void install(<b>@Tinted</b> Windshield windshield,
    197          <b>@Big</b> Trunk trunk) { ... }
    198    }</pre>
    199 
    200  <p>If one injectable method overrides another, the overriding method's
    201  parameters do not automatically inherit qualifiers from the overridden
    202  method's parameters.
    203 
    204  <h3>Injectable Values</h3>
    205 
    206  <p>For a given type T and optional qualifier, an injector must be able to
    207  inject a user-specified class that:
    208 
    209  <ol type="a">
    210    <li>is assignment compatible with T and</li>
    211    <li>has an injectable constructor.</li>
    212  </ol>
    213 
    214  <p>For example, the user might use external configuration to pick an
    215  implementation of T. Beyond that, which values are injected depend upon the
    216  injector implementation and its configuration.
    217 
    218  <h3>Circular Dependencies</h3>
    219 
    220  <p>Detecting and resolving circular dependencies is left as an exercise for
    221  the injector implementation. Circular dependencies between two constructors
    222  is an obvious problem, but you can also have a circular dependency between
    223  injectable fields or methods:
    224 
    225  <pre>
    226    class A {
    227      &#064;Inject B b;
    228    }
    229    class B {
    230      &#064;Inject A a;
    231    }</pre>
    232 
    233  <p>When constructing an instance of <code>A</code>, a naive injector
    234  implementation might go into an infinite loop constructing an instance of
    235  <code>B</code> to set on <code>A</code>, a second instance of <code>A</code> to set on
    236  <code>B</code>, a second instance of <code>B</code> to set on the second instance of
    237  <code>A</code>, and so on.
    238 
    239  <p>A conservative injector might detect the circular dependency at build
    240  time and generate an error, at which point the programmer could break the
    241  circular dependency by injecting <A HREF="../../javax/inject/Provider.html" title="interface in javax.inject"><CODE>Provider&lt;A></CODE></A> or <code>Provider&lt;B&gt;</code> instead of <code>A</code> or <code>B</code> respectively. Calling <A HREF="../../javax/inject/Provider.html#get()"><CODE>get()</CODE></A> on the provider directly from the constructor or
    242  method it was injected into defeats the provider's ability to break up
    243  circular dependencies. In the case of method or field injection, scoping
    244  one of the dependencies (using <A HREF="../../javax/inject/Singleton.html" title="annotation in javax.inject">singleton scope</A>, for
    245  example) may also enable a valid circular relationship.
    246 <P>
    247 
    248 <P>
    249 <DL>
    250 <DT><B>See Also:</B><DD><A HREF="../../javax/inject/Qualifier.html" title="annotation in javax.inject"><CODE>@Qualifier</CODE></A>, 
    251 <A HREF="../../javax/inject/Provider.html" title="interface in javax.inject"><CODE>Provider</CODE></A></DL>
    252 
    253 <P>
    254 
    255 <P>
    256 <!-- ========= END OF CLASS DATA ========= -->
    257 <HR>
    258 
    259 
    260 <!-- ======= START OF BOTTOM NAVBAR ====== -->
    261 <A NAME="navbar_bottom"><!-- --></A>
    262 <A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
    263 <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
    264 <TR>
    265 <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
    266 <A NAME="navbar_bottom_firstrow"><!-- --></A>
    267 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
    268   <TR ALIGN="center" VALIGN="top">
    269   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../javax/inject/package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
    270   <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
    271   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
    272   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
    273   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
    274   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
    275   </TR>
    276 </TABLE>
    277 </TD>
    278 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
    279 </EM>
    280 </TD>
    281 </TR>
    282 
    283 <TR>
    284 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
    285 &nbsp;PREV CLASS&nbsp;
    286 &nbsp;<A HREF="../../javax/inject/Named.html" title="annotation in javax.inject"><B>NEXT CLASS</B></A></FONT></TD>
    287 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
    288   <A HREF="../../index.html?javax/inject/Inject.html" target="_top"><B>FRAMES</B></A>  &nbsp;
    289 &nbsp;<A HREF="Inject.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
    290 &nbsp;<SCRIPT type="text/javascript">
    291   <!--
    292   if(window==top) {
    293     document.writeln('<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>');
    294   }
    295   //-->
    296 </SCRIPT>
    297 <NOSCRIPT>
    298   <A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>
    299 </NOSCRIPT>
    300 
    301 
    302 </FONT></TD>
    303 </TR>
    304 <TR>
    305 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
    306   SUMMARY:&nbsp;REQUIRED&nbsp;|&nbsp;OPTIONAL</FONT></TD>
    307 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
    308 DETAIL:&nbsp;ELEMENT</FONT></TD>
    309 </TR>
    310 </TABLE>
    311 <A NAME="skip-navbar_bottom"></A>
    312 <!-- ======== END OF BOTTOM NAVBAR ======= -->
    313 
    314 <HR>
    315 <font size='-1'>Copyright (C) 2009 <a href='http://code.google.com/p/atinject/'>The JSR-330 Expert Group</a>. Licensed under the <a href='http://www.apache.org/licenses/LICENSE-2.0'>Apache License</a>, Version 2.0.</font>
    316 </BODY>
    317 </HTML>
    318