1 /* 2 * Copyright (C) 2009 The JSR-330 Expert Group 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * This package specifies a means for obtaining objects in such a way as to 19 * maximize reusability, testability and maintainability compared to 20 * traditional approaches such as constructors, factories, and service 21 * locators (e.g., JNDI). This process, known as <i>dependency 22 * injection</i>, is beneficial to most nontrivial applications. 23 * 24 * <p>Many types depend on other types. For example, a <tt>Stopwatch</tt> might 25 * depend on a <tt>TimeSource</tt>. The types on which a type depends are 26 * known as its <i>dependencies</i>. The process of finding an instance of a 27 * dependency to use at run time is known as <i>resolving</i> the dependency. 28 * If no such instance can be found, the dependency is said to be 29 * <i>unsatisfied</i>, and the application is broken. 30 * 31 * <p>In the absence of dependency injection, an object can resolve its 32 * dependencies in a few ways. It can invoke a constructor, hard-wiring an 33 * object directly to its dependency's implementation and life cycle: 34 * 35 * <pre> class Stopwatch { 36 * final TimeSource timeSource; 37 * Stopwatch () { 38 * timeSource = <b>new AtomicClock(...)</b>; 39 * } 40 * void start() { ... } 41 * long stop() { ... } 42 * }</pre> 43 * 44 * <p>If more flexibility is needed, the object can call out to a factory or 45 * service locator: 46 * 47 * <pre> class Stopwatch { 48 * final TimeSource timeSource; 49 * Stopwatch () { 50 * timeSource = <b>DefaultTimeSource.getInstance()</b>; 51 * } 52 * void start() { ... } 53 * long stop() { ... } 54 * }</pre> 55 * 56 * <p>In deciding between these traditional approaches to dependency 57 * resolution, a programmer must make trade-offs. Constructors are more 58 * concise but restrictive. Factories decouple the client and implementation 59 * to some extent but require boilerplate code. Service locators decouple even 60 * further but reduce compile time type safety. All three approaches inhibit 61 * unit testing. For example, if the programmer uses a factory, each test 62 * against code that depends on the factory will have to mock out the factory 63 * and remember to clean up after itself or else risk side effects: 64 * 65 * <pre> void testStopwatch() { 66 * <b>TimeSource original = DefaultTimeSource.getInstance(); 67 * DefaultTimeSource.setInstance(new MockTimeSource()); 68 * try {</b> 69 * // Now, we can actually test Stopwatch. 70 * Stopwatch sw = new Stopwatch(); 71 * ... 72 * <b>} finally { 73 * DefaultTimeSource.setInstance(original); 74 * }</b> 75 * }</pre> 76 * 77 * <p>In practice, supporting this ability to mock out a factory results in 78 * even more boilerplate code. Tests that mock out and clean up after multiple 79 * dependencies quickly get out of hand. To make matters worse, a programmer 80 * must predict accurately how much flexibility will be needed in the future 81 * or else suffer the consequences. If a programmer initially elects to use a 82 * constructor but later decides that more flexibility is required, the 83 * programmer must replace every call to the constructor. If the programmer 84 * errs on the side of caution and write factories up front, it may result in 85 * a lot of unnecessary boilerplate code, adding noise, complexity, and 86 * error-proneness. 87 * 88 * <p><i>Dependency injection</i> addresses all of these issues. Instead of 89 * the programmer calling a constructor or factory, a tool called a 90 * <i>dependency injector</i> passes dependencies to objects: 91 * 92 * <pre> class Stopwatch { 93 * final TimeSource timeSource; 94 * <b>@Inject Stopwatch(TimeSource timeSource)</b> { 95 * this.timeSource = timeSource; 96 * } 97 * void start() { ... } 98 * long stop() { ... } 99 * }</pre> 100 * 101 * <p>The injector further passes dependencies to other dependencies until it 102 * constructs the entire object graph. For example, suppose the programmer 103 * asked an injector to create a <tt>StopwatchWidget</tt> instance: 104 * 105 * <pre> /** GUI for a Stopwatch */ 106 * class StopwatchWidget { 107 * @Inject StopwatchWidget(Stopwatch sw) { ... } 108 * ... 109 * }</pre> 110 * 111 * <p>The injector might: 112 * <ol> 113 * <li>Find a <tt>TimeSource</tt> 114 * <li>Construct a <tt>Stopwatch</tt> with the <tt>TimeSource</tt> 115 * <li>Construct a <tt>StopwatchWidget</tt> with the <tt>Stopwatch</tt> 116 * </ol> 117 * 118 * <p>This leaves the programmer's code clean, flexible, and relatively free 119 * of dependency-related infrastructure. 120 * 121 * <p>In unit tests, the programmer can now construct objects directly 122 * (without an injector) and pass in mock dependencies. The programmer no 123 * longer needs to set up and tear down factories or service locators in each 124 * test. This greatly simplifies our unit test: 125 * 126 * <pre> void testStopwatch() { 127 * Stopwatch sw = new Stopwatch(new MockTimeSource()); 128 * ... 129 * }</pre> 130 * 131 * <p>The total decrease in unit-test complexity is proportional to the 132 * product of the number of unit tests and the number of dependencies. 133 * 134 * <p><b>This package provides dependency injection annotations that enable 135 * portable classes</b>, but it leaves external dependency configuration up to 136 * the injector implementation. Programmers annotate constructors, methods, 137 * and fields to advertise their injectability (constructor injection is 138 * demonstrated in the examples above). A dependency injector identifies a 139 * class's dependencies by inspecting these annotations, and injects the 140 * dependencies at run time. Moreover, the injector can verify that all 141 * dependencies have been satisfied at <i>build time</i>. A service locator, 142 * by contrast, cannot detect unsatisfied dependencies until run time. 143 * 144 * <p>Injector implementations can take many forms. An injector could 145 * configure itself using XML, annotations, a DSL (domain-specific language), 146 * or even plain Java code. An injector could rely on reflection or code 147 * generation. An injector that uses compile-time code generation may not even 148 * have its own run time representation. Other injectors may not be able to 149 * generate code at all, neither at compile nor run time. A "container", for 150 * some definition, can be an injector, but this package specification aims to 151 * minimize restrictions on injector implementations. 152 * 153 * @see javax.inject.Inject @Inject 154 */ 155 package javax.inject; 156
