summaryrefslogtreecommitdiffstats
path: root/javadoc
diff options
context:
space:
mode:
authorBob Lee <crazybob@crazybob.org>2009-07-09 01:38:06 +0000
committerBob Lee <crazybob@crazybob.org>2009-07-09 01:38:06 +0000
commitba55c0ceeb98f112d798c3c8817ad1d0d7003668 (patch)
tree1df3c34e242ad57a6a475db1c7e32bc4a5e1e43f /javadoc
parent4ddb47b9f292bbcd1ba53c7cea9dc1b84d9744a0 (diff)
downloadplatform_external_jsr330-ba55c0ceeb98f112d798c3c8817ad1d0d7003668.tar.gz
platform_external_jsr330-ba55c0ceeb98f112d798c3c8817ad1d0d7003668.tar.bz2
platform_external_jsr330-ba55c0ceeb98f112d798c3c8817ad1d0d7003668.zip
Updated Javadocs.
git-svn-id: https://atinject.googlecode.com/svn/trunk@19 3bc8319c-20ab-11de-9edc-3f40a397ab60
Diffstat (limited to 'javadoc')
-rw-r--r--javadoc/allclasses-frame.html2
-rw-r--r--javadoc/allclasses-noframe.html2
-rw-r--r--javadoc/constant-values.html2
-rw-r--r--javadoc/deprecated-list.html2
-rw-r--r--javadoc/help-doc.html2
-rw-r--r--javadoc/index-files/index-1.html2
-rw-r--r--javadoc/index-files/index-2.html2
-rw-r--r--javadoc/index-files/index-3.html8
-rw-r--r--javadoc/index-files/index-4.html2
-rw-r--r--javadoc/index-files/index-5.html2
-rw-r--r--javadoc/index-files/index-6.html2
-rw-r--r--javadoc/index-files/index-7.html2
-rw-r--r--javadoc/index.html2
-rw-r--r--javadoc/javax/inject/Inject.html2
-rw-r--r--javadoc/javax/inject/Named.html2
-rw-r--r--javadoc/javax/inject/Provider.html2
-rw-r--r--javadoc/javax/inject/Qualifier.html2
-rw-r--r--javadoc/javax/inject/Scope.html2
-rw-r--r--javadoc/javax/inject/Singleton.html2
-rw-r--r--javadoc/javax/inject/package-frame.html2
-rw-r--r--javadoc/javax/inject/package-summary.html159
-rw-r--r--javadoc/javax/inject/package-tree.html2
-rw-r--r--javadoc/overview-tree.html2
23 files changed, 169 insertions, 40 deletions
diff --git a/javadoc/allclasses-frame.html b/javadoc/allclasses-frame.html
index e3ca9ef..38982ff 100644
--- a/javadoc/allclasses-frame.html
+++ b/javadoc/allclasses-frame.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
All Classes
</TITLE>
diff --git a/javadoc/allclasses-noframe.html b/javadoc/allclasses-noframe.html
index abf6b4d..ef1c781 100644
--- a/javadoc/allclasses-noframe.html
+++ b/javadoc/allclasses-noframe.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
All Classes
</TITLE>
diff --git a/javadoc/constant-values.html b/javadoc/constant-values.html
index 9d087f7..c881c79 100644
--- a/javadoc/constant-values.html
+++ b/javadoc/constant-values.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
Constant Field Values
</TITLE>
diff --git a/javadoc/deprecated-list.html b/javadoc/deprecated-list.html
index b80e482..7be7ae7 100644
--- a/javadoc/deprecated-list.html
+++ b/javadoc/deprecated-list.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
Deprecated List
</TITLE>
diff --git a/javadoc/help-doc.html b/javadoc/help-doc.html
index 8d866bf..d1c7b9b 100644
--- a/javadoc/help-doc.html
+++ b/javadoc/help-doc.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
API Help
</TITLE>
diff --git a/javadoc/index-files/index-1.html b/javadoc/index-files/index-1.html
index e48870e..7cbdcb8 100644
--- a/javadoc/index-files/index-1.html
+++ b/javadoc/index-files/index-1.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
G-Index
</TITLE>
diff --git a/javadoc/index-files/index-2.html b/javadoc/index-files/index-2.html
index c24d392..5f82421 100644
--- a/javadoc/index-files/index-2.html
+++ b/javadoc/index-files/index-2.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
I-Index
</TITLE>
diff --git a/javadoc/index-files/index-3.html b/javadoc/index-files/index-3.html
index f91ec42..a462496 100644
--- a/javadoc/index-files/index-3.html
+++ b/javadoc/index-files/index-3.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
J-Index
</TITLE>
@@ -76,7 +76,11 @@ function windowTitle()
<A NAME="_J_"><!-- --></A><H2>
<B>J</B></H2>
<DL>
-<DT><A HREF="../javax/inject/package-summary.html"><B>javax.inject</B></A> - package javax.inject<DD>Provides annotations for dependency injection.</DL>
+<DT><A HREF="../javax/inject/package-summary.html"><B>javax.inject</B></A> - package javax.inject<DD>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.</DL>
<HR>
diff --git a/javadoc/index-files/index-4.html b/javadoc/index-files/index-4.html
index 27397da..bbe7a8e 100644
--- a/javadoc/index-files/index-4.html
+++ b/javadoc/index-files/index-4.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
N-Index
</TITLE>
diff --git a/javadoc/index-files/index-5.html b/javadoc/index-files/index-5.html
index f731885..fcdc62b 100644
--- a/javadoc/index-files/index-5.html
+++ b/javadoc/index-files/index-5.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
P-Index
</TITLE>
diff --git a/javadoc/index-files/index-6.html b/javadoc/index-files/index-6.html
index 50376e7..b010d84 100644
--- a/javadoc/index-files/index-6.html
+++ b/javadoc/index-files/index-6.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
Q-Index
</TITLE>
diff --git a/javadoc/index-files/index-7.html b/javadoc/index-files/index-7.html
index ba0dc6e..f51feee 100644
--- a/javadoc/index-files/index-7.html
+++ b/javadoc/index-files/index-7.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
S-Index
</TITLE>
diff --git a/javadoc/index.html b/javadoc/index.html
index 1bfbf54..a3617a9 100644
--- a/javadoc/index.html
+++ b/javadoc/index.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc on Wed Jul 08 16:23:58 PDT 2009-->
+<!-- Generated by javadoc on Wed Jul 08 18:36:32 PDT 2009-->
<TITLE>
Generated Documentation (Untitled)
</TITLE>
diff --git a/javadoc/javax/inject/Inject.html b/javadoc/javax/inject/Inject.html
index 6a88e17..d70e1ce 100644
--- a/javadoc/javax/inject/Inject.html
+++ b/javadoc/javax/inject/Inject.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
Inject
</TITLE>
diff --git a/javadoc/javax/inject/Named.html b/javadoc/javax/inject/Named.html
index 47e4c2c..d47bc5f 100644
--- a/javadoc/javax/inject/Named.html
+++ b/javadoc/javax/inject/Named.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
Named
</TITLE>
diff --git a/javadoc/javax/inject/Provider.html b/javadoc/javax/inject/Provider.html
index 52ed2c8..af063a1 100644
--- a/javadoc/javax/inject/Provider.html
+++ b/javadoc/javax/inject/Provider.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
Provider
</TITLE>
diff --git a/javadoc/javax/inject/Qualifier.html b/javadoc/javax/inject/Qualifier.html
index c0f0e22..961baf6 100644
--- a/javadoc/javax/inject/Qualifier.html
+++ b/javadoc/javax/inject/Qualifier.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
Qualifier
</TITLE>
diff --git a/javadoc/javax/inject/Scope.html b/javadoc/javax/inject/Scope.html
index 0971bcb..8361b07 100644
--- a/javadoc/javax/inject/Scope.html
+++ b/javadoc/javax/inject/Scope.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
Scope
</TITLE>
diff --git a/javadoc/javax/inject/Singleton.html b/javadoc/javax/inject/Singleton.html
index 5330add..5cb78d2 100644
--- a/javadoc/javax/inject/Singleton.html
+++ b/javadoc/javax/inject/Singleton.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
Singleton
</TITLE>
diff --git a/javadoc/javax/inject/package-frame.html b/javadoc/javax/inject/package-frame.html
index 6b57d7d..0787c20 100644
--- a/javadoc/javax/inject/package-frame.html
+++ b/javadoc/javax/inject/package-frame.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
javax.inject
</TITLE>
diff --git a/javadoc/javax/inject/package-summary.html b/javadoc/javax/inject/package-summary.html
index 984e9c2..57af3db 100644
--- a/javadoc/javax/inject/package-summary.html
+++ b/javadoc/javax/inject/package-summary.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
javax.inject
</TITLE>
@@ -77,7 +77,11 @@ function windowTitle()
<H2>
Package javax.inject
</H2>
-Provides annotations for dependency injection.
+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>
@@ -132,21 +136,142 @@ Package javax.inject Description
</H2>
<P>
-Provides annotations for dependency injection. Enables portable objects
- but leaves external dependency configuration up to <i>the injector</i>
- implementation.
-
- <p>For the purposes of this specification, the injector is anything that
- injects objects. Injector implementations can take many forms. An injector
- could rely on code generation or reflection. An injector could configure
- itself using XML, annotations, a DSL (domain-specific language), or even
- plain Java code. A "container", for some definition, can be an injector,
- but this specification aims to minimize restrictions on injector
- implementations.
-
- <p>For example, 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.
+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>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>This package provides dependency injection annotations that enable
+ portable classes, but it leaves external dependency configuration up to the
+ injector implementation.
+
+ <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>
diff --git a/javadoc/javax/inject/package-tree.html b/javadoc/javax/inject/package-tree.html
index e7de291..e4a98c4 100644
--- a/javadoc/javax/inject/package-tree.html
+++ b/javadoc/javax/inject/package-tree.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
javax.inject Class Hierarchy
</TITLE>
diff --git a/javadoc/overview-tree.html b/javadoc/overview-tree.html
index eae0b96..4950fdb 100644
--- a/javadoc/overview-tree.html
+++ b/javadoc/overview-tree.html
@@ -2,7 +2,7 @@
<!--NewPage-->
<HTML>
<HEAD>
-<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 16:23:58 PDT 2009 -->
+<!-- Generated by javadoc (build 1.5.0_16) on Wed Jul 08 18:36:32 PDT 2009 -->
<TITLE>
Class Hierarchy
</TITLE>
generated by cgit v1.2.3 (git 2.25.1) at 2024-05-30 09:14:23 +0000