javadoc/javax/inject/package-summary.html - platform/external/jsr330 - Git at Google

 <!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 Wed Jul 08 23:41:46 CDT 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>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../index-files/index-1.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
   </TR>
 </TABLE>
 </TD>
 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
 <font color='red'><b>This is a DRAFT specification.</b></font></EM>
 </TD>
 </TR>

 <TR>
 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 &nbsp;PREV PACKAGE&nbsp;
 &nbsp;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>  &nbsp;
 &nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
 &nbsp;<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).&nbsp;This process, known as <i>dependency
  injection</i>, is beneficial to most nontrivial applications.
 <P>
 <B>See:</B>
 <BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<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&lt;T&gt;</A></B></TD>
 <TD>Provides instances of <code>T</code>.</TD>
 </TR>
 </TABLE>
 &nbsp;

 <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>
 &nbsp;

 <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).&nbsp;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 &#42;/
    class StopwatchWidget {
      &#64;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 runtime. 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>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../index-files/index-1.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
   </TR>
 </TABLE>
 </TD>
 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
 <font color='red'><b>This is a DRAFT specification.</b></font></EM>
 </TD>
 </TR>

 <TR>
 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 &nbsp;PREV PACKAGE&nbsp;
 &nbsp;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>  &nbsp;
 &nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
 &nbsp;<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 The JSR-330 Expert Group. Licensed under the <a href='http://www.apache.org/licenses/LICENSE-2.0'>Apache License</a>, Version 2.0.</font>
 </BODY>
 </HTML>
	<!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 Wed Jul 08 23:41:46 CDT 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-files/index-1.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>
	<font color='red'><b>This is a DRAFT specification.</b></font></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 runtime. 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-files/index-1.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>
	<font color='red'><b>This is a DRAFT specification.</b></font></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 The JSR-330 Expert Group. Licensed under the <a href='http://www.apache.org/licenses/LICENSE-2.0'>Apache License</a>, Version 2.0.</font>
	</BODY>
	</HTML>