You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
333 lines
13 KiB
333 lines
13 KiB
<!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>
|