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:20 PDT 2009 --> 6 <TITLE> 7 javax.inject 8 </TITLE> 9 10 <META NAME="keywords" CONTENT="javax.inject package"> 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="javax.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="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</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 PACKAGE 54 NEXT PACKAGE</FONT></TD> 55 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 56 <A HREF="../../index.html?javax/inject/package-summary.html" target="_top"><B>FRAMES</B></A> 57 <A HREF="package-summary.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 </TABLE> 73 <A NAME="skip-navbar_top"></A> 74 <!-- ========= END OF TOP NAVBAR ========= --> 75 76 <HR> 77 <H2> 78 Package javax.inject 79 </H2> 80 This package specifies a means for obtaining objects in such a way as to 81 maximize reusability, testability and maintainability compared to 82 traditional approaches such as constructors, factories, and service 83 locators (e.g., JNDI). This process, known as <i>dependency 84 injection</i>, is beneficial to most nontrivial applications. 85 <P> 86 <B>See:</B> 87 <BR> 88 <A HREF="#package_description"><B>Description</B></A> 89 <P> 90 91 <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 92 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 93 <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> 94 <B>Interface Summary</B></FONT></TH> 95 </TR> 96 <TR BGCOLOR="white" CLASS="TableRowColor"> 97 <TD WIDTH="15%"><B><A HREF="../../javax/inject/Provider.html" title="interface in javax.inject">Provider<T></A></B></TD> 98 <TD>Provides instances of <code>T</code>.</TD> 99 </TR> 100 </TABLE> 101 102 103 <P> 104 105 <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 106 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 107 <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> 108 <B>Annotation Types Summary</B></FONT></TH> 109 </TR> 110 <TR BGCOLOR="white" CLASS="TableRowColor"> 111 <TD WIDTH="15%"><B><A HREF="../../javax/inject/Inject.html" title="annotation in javax.inject">Inject</A></B></TD> 112 <TD>Identifies injectable constructors, methods, and fields.</TD> 113 </TR> 114 <TR BGCOLOR="white" CLASS="TableRowColor"> 115 <TD WIDTH="15%"><B><A HREF="../../javax/inject/Named.html" title="annotation in javax.inject">Named</A></B></TD> 116 <TD>String-based <A HREF="../../javax/inject/Qualifier.html" title="annotation in javax.inject">qualifier</A>.</TD> 117 </TR> 118 <TR BGCOLOR="white" CLASS="TableRowColor"> 119 <TD WIDTH="15%"><B><A HREF="../../javax/inject/Qualifier.html" title="annotation in javax.inject">Qualifier</A></B></TD> 120 <TD>Identifies qualifier annotations.</TD> 121 </TR> 122 <TR BGCOLOR="white" CLASS="TableRowColor"> 123 <TD WIDTH="15%"><B><A HREF="../../javax/inject/Scope.html" title="annotation in javax.inject">Scope</A></B></TD> 124 <TD>Identifies scope annotations.</TD> 125 </TR> 126 <TR BGCOLOR="white" CLASS="TableRowColor"> 127 <TD WIDTH="15%"><B><A HREF="../../javax/inject/Singleton.html" title="annotation in javax.inject">Singleton</A></B></TD> 128 <TD>Identifies a type that the injector only instantiates once.</TD> 129 </TR> 130 </TABLE> 131 132 133 <P> 134 <A NAME="package_description"><!-- --></A><H2> 135 Package javax.inject Description 136 </H2> 137 138 <P> 139 This package specifies a means for obtaining objects in such a way as to 140 maximize reusability, testability and maintainability compared to 141 traditional approaches such as constructors, factories, and service 142 locators (e.g., JNDI). This process, known as <i>dependency 143 injection</i>, is beneficial to most nontrivial applications. 144 145 <p>Many types depend on other types. For example, a <tt>Stopwatch</tt> might 146 depend on a <tt>TimeSource</tt>. The types on which a type depends are 147 known as its <i>dependencies</i>. The process of finding an instance of a 148 dependency to use at run time is known as <i>resolving</i> the dependency. 149 If no such instance can be found, the dependency is said to be 150 <i>unsatisfied</i>, and the application is broken. 151 152 <p>In the absence of dependency injection, an object can resolve its 153 dependencies in a few ways. It can invoke a constructor, hard-wiring an 154 object directly to its dependency's implementation and life cycle: 155 156 <pre> class Stopwatch { 157 final TimeSource timeSource; 158 Stopwatch () { 159 timeSource = <b>new AtomicClock(...)</b>; 160 } 161 void start() { ... } 162 long stop() { ... } 163 }</pre> 164 165 <p>If more flexibility is needed, the object can call out to a factory or 166 service locator: 167 168 <pre> class Stopwatch { 169 final TimeSource timeSource; 170 Stopwatch () { 171 timeSource = <b>DefaultTimeSource.getInstance()</b>; 172 } 173 void start() { ... } 174 long stop() { ... } 175 }</pre> 176 177 <p>In deciding between these traditional approaches to dependency 178 resolution, a programmer must make trade-offs. Constructors are more 179 concise but restrictive. Factories decouple the client and implementation 180 to some extent but require boilerplate code. Service locators decouple even 181 further but reduce compile time type safety. All three approaches inhibit 182 unit testing. For example, if the programmer uses a factory, each test 183 against code that depends on the factory will have to mock out the factory 184 and remember to clean up after itself or else risk side effects: 185 186 <pre> void testStopwatch() { 187 <b>TimeSource original = DefaultTimeSource.getInstance(); 188 DefaultTimeSource.setInstance(new MockTimeSource()); 189 try {</b> 190 // Now, we can actually test Stopwatch. 191 Stopwatch sw = new Stopwatch(); 192 ... 193 <b>} finally { 194 DefaultTimeSource.setInstance(original); 195 }</b> 196 }</pre> 197 198 <p>In practice, supporting this ability to mock out a factory results in 199 even more boilerplate code. Tests that mock out and clean up after multiple 200 dependencies quickly get out of hand. To make matters worse, a programmer 201 must predict accurately how much flexibility will be needed in the future 202 or else suffer the consequences. If a programmer initially elects to use a 203 constructor but later decides that more flexibility is required, the 204 programmer must replace every call to the constructor. If the programmer 205 errs on the side of caution and write factories up front, it may result in 206 a lot of unnecessary boilerplate code, adding noise, complexity, and 207 error-proneness. 208 209 <p><i>Dependency injection</i> addresses all of these issues. Instead of 210 the programmer calling a constructor or factory, a tool called a 211 <i>dependency injector</i> passes dependencies to objects: 212 213 <pre> class Stopwatch { 214 final TimeSource timeSource; 215 <b>@Inject Stopwatch(TimeSource TimeSource)</b> { 216 this.TimeSource = TimeSource; 217 } 218 void start() { ... } 219 long stop() { ... } 220 }</pre> 221 222 <p>The injector further passes dependencies to other dependencies until it 223 constructs the entire object graph. For example, suppose the programmer 224 asked an injector to create a <tt>StopwatchWidget</tt> instance: 225 226 <pre> /** GUI for a Stopwatch */ 227 class StopwatchWidget { 228 @Inject StopwatchWidget(Stopwatch sw) { ... } 229 ... 230 }</pre> 231 232 <p>The injector might: 233 <ol> 234 <li>Find a <tt>TimeSource</tt> 235 <li>Construct a <tt>Stopwatch</tt> with the <tt>TimeSource</tt> 236 <li>Construct a <tt>StopwatchWidget</tt> with the <tt>Stopwatch</tt> 237 </ol> 238 239 <p>This leaves the programmer's code clean, flexible, and relatively free 240 of dependency-related infrastructure. 241 242 <p>In unit tests, the programmer can now construct objects directly 243 (without an injector) and pass in mock dependencies. The programmer no 244 longer needs to set up and tear down factories or service locators in each 245 test. This greatly simplifies our unit test: 246 247 <pre> void testStopwatch() { 248 Stopwatch sw = new Stopwatch(new MockTimeSource()); 249 ... 250 }</pre> 251 252 <p>The total decrease in unit-test complexity is proportional to the 253 product of the number of unit tests and the number of dependencies. 254 255 <p><b>This package provides dependency injection annotations that enable 256 portable classes</b>, but it leaves external dependency configuration up to 257 the injector implementation. Programmers annotate constructors, methods, 258 and fields to advertise their injectability (constructor injection is 259 demonstrated in the examples above). A dependency injector identifies a 260 class's dependencies by inspecting these annotations, and injects the 261 dependencies at run time. Moreover, the injector can verify that all 262 dependencies have been satisfied at <i>build time</i>. A service locator, 263 by contrast, cannot detect unsatisfied dependencies until run time. 264 265 <p>Injector implementations can take many forms. An injector could 266 configure itself using XML, annotations, a DSL (domain-specific language), 267 or even plain Java code. An injector could rely on reflection or code 268 generation. An injector that uses compile-time code generation may not even 269 have its own run time representation. Other injectors may not be able to 270 generate code at all, neither at compile nor run time. A "container", for 271 some definition, can be an injector, but this package specification aims to 272 minimize restrictions on injector implementations. 273 <P> 274 275 <P> 276 <DL> 277 <DT><B>See Also:</B><DD><A HREF="../../javax/inject/Inject.html" title="annotation in javax.inject"><CODE>@Inject</CODE></A></DL> 278 <HR> 279 280 281 <!-- ======= START OF BOTTOM NAVBAR ====== --> 282 <A NAME="navbar_bottom"><!-- --></A> 283 <A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> 284 <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> 285 <TR> 286 <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> 287 <A NAME="navbar_bottom_firstrow"><!-- --></A> 288 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> 289 <TR ALIGN="center" VALIGN="top"> 290 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../javax/inject/package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> 291 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> 292 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 293 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 294 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 295 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> 296 </TR> 297 </TABLE> 298 </TD> 299 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> 300 </EM> 301 </TD> 302 </TR> 303 304 <TR> 305 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 306 PREV PACKAGE 307 NEXT PACKAGE</FONT></TD> 308 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 309 <A HREF="../../index.html?javax/inject/package-summary.html" target="_top"><B>FRAMES</B></A> 310 <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> 311 <SCRIPT type="text/javascript"> 312 <!-- 313 if(window==top) { 314 document.writeln('<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>'); 315 } 316 //--> 317 </SCRIPT> 318 <NOSCRIPT> 319 <A HREF="../../allclasses-noframe.html"><B>All Classes</B></A> 320 </NOSCRIPT> 321 322 323 </FONT></TD> 324 </TR> 325 </TABLE> 326 <A NAME="skip-navbar_bottom"></A> 327 <!-- ======== END OF BOTTOM NAVBAR ======= --> 328 329 <HR> 330 <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> 331 </BODY> 332 </HTML> 333
