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