diff options
Diffstat (limited to 'javadoc/javax/inject/package-summary.html')
| -rw-r--r-- | javadoc/javax/inject/package-summary.html | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/javadoc/javax/inject/package-summary.html b/javadoc/javax/inject/package-summary.html new file mode 100644 index 0000000..a1dd828 --- /dev/null +++ b/javadoc/javax/inject/package-summary.html @@ -0,0 +1,332 @@ +<!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> |