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> 7Inject 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"> 15function 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> </TD> 38 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> 39 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 40 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 41 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 42 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </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 PREV CLASS 54 <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> 57 <A HREF="Inject.html" target="_top"><B>NO FRAMES</B></A> 58 <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: REQUIRED | OPTIONAL</FONT></TD> 75<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 76DETAIL: 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"> 86javax.inject</FONT> 87<BR> 88Annotation 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> 98Identifies 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 @Inject public Car(Engine engine) { ... } 164 165 // Injectable field 166 @Inject private Provider<Seat> seatProvider; 167 168 // Injectable package-private method 169 @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 @Inject private <b>@Leather</b> Provider<Seat> seatProvider; 195 196 @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 @Inject B b; 228 } 229 class B { 230 @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<A></CODE></A> or <code>Provider<B></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> </TD> 270 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> 271 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 272 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 273 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 274 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </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 PREV CLASS 286 <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> 289 <A HREF="Inject.html" target="_top"><B>NO FRAMES</B></A> 290 <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: REQUIRED | OPTIONAL</FONT></TD> 307<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 308DETAIL: 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