diff options
Diffstat (limited to 'src/javax')
| -rw-r--r-- | src/javax/inject/Inject.java | 185 | ||||
| -rw-r--r-- | src/javax/inject/Named.java | 42 | ||||
| -rw-r--r-- | src/javax/inject/Provider.java | 57 | ||||
| -rw-r--r-- | src/javax/inject/Qualifier.java | 58 | ||||
| -rw-r--r-- | src/javax/inject/Scope.java | 79 | ||||
| -rw-r--r-- | src/javax/inject/Singleton.java | 31 | ||||
| -rw-r--r-- | src/javax/inject/package-info.java | 155 |
7 files changed, 607 insertions, 0 deletions
diff --git a/src/javax/inject/Inject.java b/src/javax/inject/Inject.java new file mode 100644 index 0000000..43458f8 --- /dev/null +++ b/src/javax/inject/Inject.java @@ -0,0 +1,185 @@ +/* + * Copyright (C) 2009 The JSR-330 Expert Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.inject; + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.Documented; +import static java.lang.annotation.RetentionPolicy.RUNTIME; +import static java.lang.annotation.ElementType.METHOD; +import static java.lang.annotation.ElementType.CONSTRUCTOR; +import static java.lang.annotation.ElementType.FIELD; + +/** + * Identifies injectable constructors, methods, and fields. May apply to static + * as well as instance members. An injectable member may have any access + * modifier (private, package-private, protected, public). Constructors are + * injected first, followed by fields, and then methods. Fields and methods + * in superclasses are injected before those in subclasses. Ordering of + * injection among fields and among methods in the same class is not specified. + * + * <p>Injectable constructors are annotated with {@code @Inject} and accept + * zero or more dependencies as arguments. {@code @Inject} can apply to at most + * one constructor per class. + * + * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject + * <i>ConstructorModifiers<sub>opt</sub></i> + * <i>SimpleTypeName</i>(<i>FormalParameterList<sub>opt</sub></i>) + * <i>Throws<sub>opt</sub></i> + * <i>ConstructorBody</i></blockquote></tt> + * + * <p>{@code @Inject} is optional for public, no-argument constructors when no + * other constructors are present. This enables injectors to invoke default + * constructors. + * + * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;"> + * {@literal @}Inject<sub><i>opt</i></sub> + * <i>Annotations<sub>opt</sub></i> + * public + * <i>SimpleTypeName</i>() + * <i>Throws<sub>opt</sub></i> + * <i>ConstructorBody</i></blockquote></tt> + * + * <p>Injectable fields: + * <ul> + * <li>are annotated with {@code @Inject}. + * <li>are not final. + * <li>may have any otherwise valid name.</li></ul> + * + * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject + * <i>FieldModifiers<sub>opt</sub></i> + * <i>Type</i> + * <i>VariableDeclarators</i>;</blockquote></tt> + * + * <p>Injectable methods: + * <ul> + * <li>are annotated with {@code @Inject}.</li> + * <li>are not abstract.</li> + * <li>do not declare type parameters of their own.</li> + * <li>may return a result</li> + * <li>may have any otherwise valid name.</li> + * <li>accept zero or more dependencies as arguments.</li></ul> + * + * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject + * <i>MethodModifiers<sub>opt</sub></i> + * <i>ResultType</i> + * <i>Identifier</i>(<i>FormalParameterList<sub>opt</sub></i>) + * <i>Throws<sub>opt</sub></i> + * <i>MethodBody</i></blockquote></tt> + * + * <p>The injector ignores the result of an injected method, but + * non-{@code void} return types are allowed to support use of the method in + * other contexts (builder-style method chaining, for example). + * + * <p>Examples: + * + * <pre> + * public class Car { + * // Injectable constructor + * @Inject public Car(Engine engine) { ... } + * + * // Injectable field + * @Inject private Provider<Seat> seatProvider; + * + * // Injectable package-private method + * @Inject void install(Windshield windshield, Trunk trunk) { ... } + * }</pre> + * + * <p>A method annotated with {@code @Inject} that overrides another method + * annotated with {@code @Inject} will only be injected once per injection + * request per instance. A method with <i>no</i> {@code @Inject} annotation + * that overrides a method annotated with {@code @Inject} will not be + * injected. + * + * <p>Injection of members annotated with {@code @Inject} is required. While an + * injectable member may use any accessibility modifier (including + * <tt>private</tt>), platform or injector limitations (like security + * restrictions or lack of reflection support) might preclude injection + * of non-public members. + * + * <h3>Qualifiers</h3> + * + * <p>A {@linkplain Qualifier qualifier} may annotate an injectable field + * or parameter and, combined with the type, identify the implementation to + * inject. Qualifiers are optional, and when used with {@code @Inject} in + * injector-independent classes, no more than one qualifier should annotate a + * single field or parameter. The qualifiers are bold in the following example: + * + * <pre> + * public class Car { + * @Inject private <b>@Leather</b> Provider<Seat> seatProvider; + * + * @Inject void install(<b>@Tinted</b> Windshield windshield, + * <b>@Big</b> Trunk trunk) { ... } + * }</pre> + * + * <p>If one injectable method overrides another, the overriding method's + * parameters do not automatically inherit qualifiers from the overridden + * method's parameters. + * + * <h3>Injectable Values</h3> + * + * <p>For a given type T and optional qualifier, an injector must be able to + * inject a user-specified class that: + * + * <ol type="a"> + * <li>is assignment compatible with T and</li> + * <li>has an injectable constructor.</li> + * </ol> + * + * <p>For example, the user might use external configuration to pick an + * implementation of T. Beyond that, which values are injected depend upon the + * injector implementation and its configuration. + * + * <h3>Circular Dependencies</h3> + * + * <p>Detecting and resolving circular dependencies is left as an exercise for + * the injector implementation. Circular dependencies between two constructors + * is an obvious problem, but you can also have a circular dependency between + * injectable fields or methods: + * + * <pre> + * class A { + * @Inject B b; + * } + * class B { + * @Inject A a; + * }</pre> + * + * <p>When constructing an instance of {@code A}, a naive injector + * implementation might go into an infinite loop constructing an instance of + * {@code B} to set on {@code A}, a second instance of {@code A} to set on + * {@code B}, a second instance of {@code B} to set on the second instance of + * {@code A}, and so on. + * + * <p>A conservative injector might detect the circular dependency at build + * time and generate an error, at which point the programmer could break the + * circular dependency by injecting {@link Provider Provider<A>} or {@code + * Provider<B>} instead of {@code A} or {@code B} respectively. Calling {@link + * Provider#get() get()} on the provider directly from the constructor or + * method it was injected into defeats the provider's ability to break up + * circular dependencies. In the case of method or field injection, scoping + * one of the dependencies (using {@linkplain Singleton singleton scope}, for + * example) may also enable a valid circular relationship. + * + * @see javax.inject.Qualifier @Qualifier + * @see javax.inject.Provider + */ +@Target({ METHOD, CONSTRUCTOR, FIELD }) +@Retention(RUNTIME) +@Documented +public @interface Inject {} diff --git a/src/javax/inject/Named.java b/src/javax/inject/Named.java new file mode 100644 index 0000000..2fb4cab --- /dev/null +++ b/src/javax/inject/Named.java @@ -0,0 +1,42 @@ +/* + * Copyright (C) 2009 The JSR-330 Expert Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.inject; + +import java.lang.annotation.Retention; +import java.lang.annotation.Documented; +import static java.lang.annotation.RetentionPolicy.RUNTIME; + +/** + * String-based {@linkplain Qualifier qualifier}. + * + * <p>Example usage: + * + * <pre> + * public class Car { + * @Inject <b>@Named("driver")</b> Seat driverSeat; + * @Inject <b>@Named("passenger")</b> Seat passengerSeat; + * ... + * }</pre> + */ +@Qualifier +@Documented +@Retention(RUNTIME) +public @interface Named { + + /** The name. */ + String value() default ""; +} diff --git a/src/javax/inject/Provider.java b/src/javax/inject/Provider.java new file mode 100644 index 0000000..271c373 --- /dev/null +++ b/src/javax/inject/Provider.java @@ -0,0 +1,57 @@ +/* + * Copyright (C) 2009 The JSR-330 Expert Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.inject; + +/** + * Provides instances of {@code T}. Typically implemented by an injector. For + * any type {@code T} that can be injected, you can also inject + * {@code Provider<T>}. Compared to injecting {@code T} directly, injecting + * {@code Provider<T>} enables: + * + * <ul> + * <li>retrieving multiple instances.</li> + * <li>lazy or optional retrieval of an instance.</li> + * <li>breaking circular dependencies.</li> + * <li>abstracting scope so you can look up an instance in a smaller scope + * from an instance in a containing scope.</li> + * </ul> + * + * <p>For example: + * + * <pre> + * class Car { + * @Inject Car(Provider<Seat> seatProvider) { + * Seat driver = seatProvider.get(); + * Seat passenger = seatProvider.get(); + * ... + * } + * }</pre> + */ +public interface Provider<T> { + + /** + * Provides a fully-constructed and injected instance of {@code T}. + * + * @throws RuntimeException if the injector encounters an error while + * providing an instance. For example, if an injectable member on + * {@code T} throws an exception, the injector may wrap the exception + * and throw it to the caller of {@code get()}. Callers should not try + * to handle such exceptions as the behavior may vary across injector + * implementations and even different configurations of the same injector. + */ + T get(); +} diff --git a/src/javax/inject/Qualifier.java b/src/javax/inject/Qualifier.java new file mode 100644 index 0000000..6b4c42d --- /dev/null +++ b/src/javax/inject/Qualifier.java @@ -0,0 +1,58 @@ +/* + * Copyright (C) 2009 The JSR-330 Expert Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.inject; + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.Documented; +import static java.lang.annotation.RetentionPolicy.RUNTIME; +import static java.lang.annotation.ElementType.ANNOTATION_TYPE; + +/** + * Identifies qualifier annotations. Anyone can define a new qualifier. A + * qualifier annotation: + * + * <ul> + * <li>is annotated with {@code @Qualifier}, {@code @Retention(RUNTIME)}, + * and typically {@code @Documented}.</li> + * <li>can have attributes.</li> + * <li>may be part of the public API, much like the dependency type, but + * unlike implementation types which needn't be part of the public + * API.</li> + * <li>may have restricted usage if annotated with {@code @Target}. While + * this specification covers applying qualifiers to fields and + * parameters only, some injector configurations might use qualifier + * annotations in other places (on methods or classes for example).</li> + * </ul> + * + * <p>For example: + * + * <pre> + * @java.lang.annotation.Documented + * @java.lang.annotation.Retention(RUNTIME) + * @javax.inject.Qualifier + * public @interface Leather { + * Color color() default Color.TAN; + * public enum Color { RED, BLACK, TAN } + * }</pre> + * + * @see javax.inject.Named @Named + */ +@Target(ANNOTATION_TYPE) +@Retention(RUNTIME) +@Documented +public @interface Qualifier {} diff --git a/src/javax/inject/Scope.java b/src/javax/inject/Scope.java new file mode 100644 index 0000000..27133f1 --- /dev/null +++ b/src/javax/inject/Scope.java @@ -0,0 +1,79 @@ +/* + * Copyright (C) 2009 The JSR-330 Expert Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.inject; + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.Documented; +import static java.lang.annotation.RetentionPolicy.RUNTIME; +import static java.lang.annotation.ElementType.ANNOTATION_TYPE; + +/** + * Identifies scope annotations. A scope annotation applies to a class + * containing an injectable constructor and governs how the injector reuses + * instances of the type. By default, if no scope annotation is present, the + * injector creates an instance (by injecting the type's constructor), uses + * the instance for one injection, and then forgets it. If a scope annotation + * is present, the injector may retain the instance for possible reuse in a + * later injection. If multiple threads can access a scoped instance, its + * implementation should be thread safe. The implementation of the scope + * itself is left up to the injector. + * + * <p>In the following example, the scope annotation {@code @Singleton} ensures + * that we only have one Log instance: + * + * <pre> + * @Singleton + * class Log { + * void log(String message) { ... } + * }</pre> + * + * <p>The injector generates an error if it encounters more than one scope + * annotation on the same class or a scope annotation it doesn't support. + * + * <p>A scope annotation: + * <ul> + * <li>is annotated with {@code @Scope}, {@code @Retention(RUNTIME)}, + * and typically {@code @Documented}.</li> + * <li>should not have attributes.</li> + * <li>is typically not {@code @Inherited}, so scoping is orthogonal to + * implementation inheritance.</li> + * <li>may have restricted usage if annotated with {@code @Target}. While + * this specification covers applying scopes to classes only, some + * injector configurations might use scope annotations + * in other places (on factory method results for example).</li> + * </ul> + * + * <p>For example: + * + * <pre> + * @java.lang.annotation.Documented + * @java.lang.annotation.Retention(RUNTIME) + * @javax.inject.Scope + * public @interface RequestScoped {}</pre> + * + * <p>Annotating scope annotations with {@code @Scope} helps the injector + * detect the case where a programmer used the scope annotation on a class but + * forgot to configure the scope in the injector. A conservative injector + * would generate an error rather than not apply a scope. + * + * @see javax.inject.Singleton @Singleton + */ +@Target(ANNOTATION_TYPE) +@Retention(RUNTIME) +@Documented +public @interface Scope {} diff --git a/src/javax/inject/Singleton.java b/src/javax/inject/Singleton.java new file mode 100644 index 0000000..a2af7b9 --- /dev/null +++ b/src/javax/inject/Singleton.java @@ -0,0 +1,31 @@ +/* + * Copyright (C) 2009 The JSR-330 Expert Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.inject; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import static java.lang.annotation.RetentionPolicy.RUNTIME; + +/** + * Identifies a type that the injector only instantiates once. Not inherited. + * + * @see javax.inject.Scope @Scope + */ +@Scope +@Documented +@Retention(RUNTIME) +public @interface Singleton {} diff --git a/src/javax/inject/package-info.java b/src/javax/inject/package-info.java new file mode 100644 index 0000000..5247410 --- /dev/null +++ b/src/javax/inject/package-info.java @@ -0,0 +1,155 @@ +/* + * Copyright (C) 2009 The JSR-330 Expert Group + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * 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. + * + * @see javax.inject.Inject @Inject + */ +package javax.inject; |