diff options
author | Bob Lee <crazybob@crazybob.org> | 2009-07-09 01:38:06 +0000 |
---|---|---|
committer | Bob Lee <crazybob@crazybob.org> | 2009-07-09 01:38:06 +0000 |
commit | ba55c0ceeb98f112d798c3c8817ad1d0d7003668 (patch) | |
tree | 1df3c34e242ad57a6a475db1c7e32bc4a5e1e43f | |
parent | 4ddb47b9f292bbcd1ba53c7cea9dc1b84d9744a0 (diff) | |
download | jsr330-ba55c0ceeb98f112d798c3c8817ad1d0d7003668.tar.gz |
Updated Javadocs.
git-svn-id: https://atinject.googlecode.com/svn/trunk@19 3bc8319c-20ab-11de-9edc-3f40a397ab60
24 files changed, 172 insertions, 40 deletions
diff --git a/atinject.ipr b/atinject.ipr index 09dc0fa..b8fd738 100644 --- a/atinject.ipr +++ b/atinject.ipr @@ -44,6 +44,9 @@ <option name="MAXIMUM_HEAP_SIZE" value="128" /> </component> <component name="Encoding" useUTFGuessing="true" native2AsciiForPropertiesFiles="false" /> + <component name="EntryPointsManager"> + <entry_points version="2.0" /> + </component> <component name="IdProvider" IDEtalkID="293ECBF8C3B5C62E10353C1DB8516323" /> <component name="InspectionProjectProfileManager"> <option name="PROJECT_PROFILE" value="Project Default" /> 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). 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). 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). 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>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> |