| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!--NewPage--> |
| <HTML> |
| <HEAD> |
| <!-- Generated by javadoc (build 1.5.0_16) on Mon Oct 12 16:11:20 PDT 2009 --> |
| <TITLE> |
| javax.inject |
| </TITLE> |
| |
| <META NAME="keywords" CONTENT="javax.inject package"> |
| |
| <LINK REL ="stylesheet" TYPE="text/css" HREF="../../stylesheet.css" TITLE="Style"> |
| |
| <SCRIPT type="text/javascript"> |
| function windowTitle() |
| { |
| parent.document.title="javax.inject"; |
| } |
| </SCRIPT> |
| <NOSCRIPT> |
| </NOSCRIPT> |
| |
| </HEAD> |
| |
| <BODY BGCOLOR="white" onload="windowTitle();"> |
| |
| |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <A NAME="navbar_top"><!-- --></A> |
| <A HREF="#skip-navbar_top" title="Skip navigation links"></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> |
| <TR> |
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> |
| <A NAME="navbar_top_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> |
| <TR ALIGN="center" VALIGN="top"> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../javax/inject/package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> |
| </TR> |
| </TABLE> |
| </TD> |
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> |
| </EM> |
| </TD> |
| </TR> |
| |
| <TR> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| PREV PACKAGE |
| NEXT PACKAGE</FONT></TD> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../index.html?javax/inject/package-summary.html" target="_top"><B>FRAMES</B></A> |
| <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> |
| <SCRIPT type="text/javascript"> |
| <!-- |
| if(window==top) { |
| document.writeln('<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>'); |
| } |
| //--> |
| </SCRIPT> |
| <NOSCRIPT> |
| <A HREF="../../allclasses-noframe.html"><B>All Classes</B></A> |
| </NOSCRIPT> |
| |
| |
| </FONT></TD> |
| </TR> |
| </TABLE> |
| <A NAME="skip-navbar_top"></A> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| |
| <HR> |
| <H2> |
| Package javax.inject |
| </H2> |
| This package specifies a means for obtaining objects in such a way as to |
| maximize reusability, testability and maintainability compared to |
| traditional approaches such as constructors, factories, and service |
| locators (e.g., JNDI). This process, known as <i>dependency |
| injection</i>, is beneficial to most nontrivial applications. |
| <P> |
| <B>See:</B> |
| <BR> |
| <A HREF="#package_description"><B>Description</B></A> |
| <P> |
| |
| <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> |
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> |
| <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> |
| <B>Interface Summary</B></FONT></TH> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../javax/inject/Provider.html" title="interface in javax.inject">Provider<T></A></B></TD> |
| <TD>Provides instances of <code>T</code>.</TD> |
| </TR> |
| </TABLE> |
| |
| |
| <P> |
| |
| <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> |
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> |
| <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> |
| <B>Annotation Types Summary</B></FONT></TH> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../javax/inject/Inject.html" title="annotation in javax.inject">Inject</A></B></TD> |
| <TD>Identifies injectable constructors, methods, and fields.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../javax/inject/Named.html" title="annotation in javax.inject">Named</A></B></TD> |
| <TD>String-based <A HREF="../../javax/inject/Qualifier.html" title="annotation in javax.inject">qualifier</A>.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../javax/inject/Qualifier.html" title="annotation in javax.inject">Qualifier</A></B></TD> |
| <TD>Identifies qualifier annotations.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../javax/inject/Scope.html" title="annotation in javax.inject">Scope</A></B></TD> |
| <TD>Identifies scope annotations.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="../../javax/inject/Singleton.html" title="annotation in javax.inject">Singleton</A></B></TD> |
| <TD>Identifies a type that the injector only instantiates once.</TD> |
| </TR> |
| </TABLE> |
| |
| |
| <P> |
| <A NAME="package_description"><!-- --></A><H2> |
| Package javax.inject Description |
| </H2> |
| |
| <P> |
| This package specifies a means for obtaining objects in such a way as to |
| maximize reusability, testability and maintainability compared to |
| traditional approaches such as constructors, factories, and service |
| locators (e.g., JNDI). This process, known as <i>dependency |
| injection</i>, is beneficial to most nontrivial applications. |
| |
| <p>Many types depend on other types. For example, a <tt>Stopwatch</tt> might |
| depend on a <tt>TimeSource</tt>. The types on which a type depends are |
| known as its <i>dependencies</i>. The process of finding an instance of a |
| dependency to use at run time is known as <i>resolving</i> the dependency. |
| If no such instance can be found, the dependency is said to be |
| <i>unsatisfied</i>, and the application is broken. |
| |
| <p>In the absence of dependency injection, an object can resolve its |
| dependencies in a few ways. It can invoke a constructor, hard-wiring an |
| object directly to its dependency's implementation and life cycle: |
| |
| <pre> class Stopwatch { |
| final TimeSource timeSource; |
| Stopwatch () { |
| timeSource = <b>new AtomicClock(...)</b>; |
| } |
| void start() { ... } |
| long stop() { ... } |
| }</pre> |
| |
| <p>If more flexibility is needed, the object can call out to a factory or |
| service locator: |
| |
| <pre> class Stopwatch { |
| final TimeSource timeSource; |
| Stopwatch () { |
| timeSource = <b>DefaultTimeSource.getInstance()</b>; |
| } |
| void start() { ... } |
| long stop() { ... } |
| }</pre> |
| |
| <p>In deciding between these traditional approaches to dependency |
| resolution, a programmer must make trade-offs. Constructors are more |
| concise but restrictive. Factories decouple the client and implementation |
| to some extent but require boilerplate code. Service locators decouple even |
| further but reduce compile time type safety. All three approaches inhibit |
| unit testing. For example, if the programmer uses a factory, each test |
| against code that depends on the factory will have to mock out the factory |
| and remember to clean up after itself or else risk side effects: |
| |
| <pre> void testStopwatch() { |
| <b>TimeSource original = DefaultTimeSource.getInstance(); |
| DefaultTimeSource.setInstance(new MockTimeSource()); |
| try {</b> |
| // Now, we can actually test Stopwatch. |
| Stopwatch sw = new Stopwatch(); |
| ... |
| <b>} finally { |
| DefaultTimeSource.setInstance(original); |
| }</b> |
| }</pre> |
| |
| <p>In practice, supporting this ability to mock out a factory results in |
| even more boilerplate code. Tests that mock out and clean up after multiple |
| dependencies quickly get out of hand. To make matters worse, a programmer |
| must predict accurately how much flexibility will be needed in the future |
| or else suffer the consequences. If a programmer initially elects to use a |
| constructor but later decides that more flexibility is required, the |
| programmer must replace every call to the constructor. If the programmer |
| errs on the side of caution and write factories up front, it may result in |
| a lot of unnecessary boilerplate code, adding noise, complexity, and |
| error-proneness. |
| |
| <p><i>Dependency injection</i> addresses all of these issues. Instead of |
| the programmer calling a constructor or factory, a tool called a |
| <i>dependency injector</i> passes dependencies to objects: |
| |
| <pre> class Stopwatch { |
| final TimeSource timeSource; |
| <b>@Inject Stopwatch(TimeSource TimeSource)</b> { |
| this.TimeSource = TimeSource; |
| } |
| void start() { ... } |
| long stop() { ... } |
| }</pre> |
| |
| <p>The injector further passes dependencies to other dependencies until it |
| constructs the entire object graph. For example, suppose the programmer |
| asked an injector to create a <tt>StopwatchWidget</tt> instance: |
| |
| <pre> /** GUI for a Stopwatch */ |
| class StopwatchWidget { |
| @Inject StopwatchWidget(Stopwatch sw) { ... } |
| ... |
| }</pre> |
| |
| <p>The injector might: |
| <ol> |
| <li>Find a <tt>TimeSource</tt> |
| <li>Construct a <tt>Stopwatch</tt> with the <tt>TimeSource</tt> |
| <li>Construct a <tt>StopwatchWidget</tt> with the <tt>Stopwatch</tt> |
| </ol> |
| |
| <p>This leaves the programmer's code clean, flexible, and relatively free |
| of dependency-related infrastructure. |
| |
| <p>In unit tests, the programmer can now construct objects directly |
| (without an injector) and pass in mock dependencies. The programmer no |
| longer needs to set up and tear down factories or service locators in each |
| test. This greatly simplifies our unit test: |
| |
| <pre> void testStopwatch() { |
| Stopwatch sw = new Stopwatch(new MockTimeSource()); |
| ... |
| }</pre> |
| |
| <p>The total decrease in unit-test complexity is proportional to the |
| product of the number of unit tests and the number of dependencies. |
| |
| <p><b>This package provides dependency injection annotations that enable |
| portable classes</b>, but it leaves external dependency configuration up to |
| the injector implementation. Programmers annotate constructors, methods, |
| and fields to advertise their injectability (constructor injection is |
| demonstrated in the examples above). A dependency injector identifies a |
| class's dependencies by inspecting these annotations, and injects the |
| dependencies at run time. Moreover, the injector can verify that all |
| dependencies have been satisfied at <i>build time</i>. A service locator, |
| by contrast, cannot detect unsatisfied dependencies until run time. |
| |
| <p>Injector implementations can take many forms. An injector could |
| configure itself using XML, annotations, a DSL (domain-specific language), |
| or even plain Java code. An injector could rely on reflection or code |
| generation. An injector that uses compile-time code generation may not even |
| have its own run time representation. Other injectors may not be able to |
| generate code at all, neither at compile nor run time. A "container", for |
| some definition, can be an injector, but this package specification aims to |
| minimize restrictions on injector implementations. |
| <P> |
| |
| <P> |
| <DL> |
| <DT><B>See Also:</B><DD><A HREF="../../javax/inject/Inject.html" title="annotation in javax.inject"><CODE>@Inject</CODE></A></DL> |
| <HR> |
| |
| |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <A NAME="navbar_bottom"><!-- --></A> |
| <A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> |
| <TR> |
| <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> |
| <A NAME="navbar_bottom_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> |
| <TR ALIGN="center" VALIGN="top"> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../javax/inject/package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> |
| </TR> |
| </TABLE> |
| </TD> |
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> |
| </EM> |
| </TD> |
| </TR> |
| |
| <TR> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| PREV PACKAGE |
| NEXT PACKAGE</FONT></TD> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../index.html?javax/inject/package-summary.html" target="_top"><B>FRAMES</B></A> |
| <A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> |
| <SCRIPT type="text/javascript"> |
| <!-- |
| if(window==top) { |
| document.writeln('<A HREF="../../allclasses-noframe.html"><B>All Classes</B></A>'); |
| } |
| //--> |
| </SCRIPT> |
| <NOSCRIPT> |
| <A HREF="../../allclasses-noframe.html"><B>All Classes</B></A> |
| </NOSCRIPT> |
| |
| |
| </FONT></TD> |
| </TR> |
| </TABLE> |
| <A NAME="skip-navbar_bottom"></A> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| |
| <HR> |
| <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> |
| </BODY> |
| </HTML> |