/*
* 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.
Injectable constructors are annotated with @Inject and accept zero or more dependencies as arguments. @Inject can apply to at most one constructor per class.
@Inject
ConstructorModifiersopt
SimpleTypeName(FormalParameterListopt)
Throwsopt
ConstructorBody
@Inject is optional for public, no-argument constructors when no other constructors are present. This enables injectors to invoke default constructors.
@Injectopt
Annotationsopt
public
SimpleTypeName()
Throwsopt
ConstructorBody
Injectable fields:
- are annotated with
@Inject. - are not final.
- may have any otherwise valid name.
@Inject
FieldModifiersopt
Type
VariableDeclarators;
Injectable methods:
- are annotated with
@Inject.
- are not abstract.
- do not declare type parameters of their own.
- may return a result
- may have any otherwise valid name.
- accept zero or more dependencies as arguments.
@Inject
MethodModifiersopt
ResultType
Identifier(FormalParameterListopt)
Throwsopt
MethodBody
The injector ignores the result of an injected method, but non-void return types are allowed to support use of the method in other contexts (builder-style method chaining, for example).
Examples:
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) { ... }
}
A method annotated with @Inject that overrides another method annotated with @Inject will only be injected once per injection request per instance. A method with no @Inject annotation that overrides a method annotated with @Inject will not be injected.
Injection of members annotated with @Inject is required. While an injectable member may use any accessibility modifier (including private), platform or injector limitations (like security
restrictions or lack of reflection support) might preclude injection
of non-public members.
Qualifiers
A 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 @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:
public class Car {
@Inject private @Leather Provider<Seat> seatProvider;
@Inject void install(@Tinted Windshield windshield,
@Big Trunk trunk) { ... }
}
If one injectable method overrides another, the overriding method's
parameters do not automatically inherit qualifiers from the overridden
method's parameters.
Injectable Values
For a given type T and optional qualifier, an injector must be able to
inject a user-specified class that:
- is assignment compatible with T and
- has an injectable constructor.
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.
Circular Dependencies
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:
class A {
@Inject B b;
}
class B {
@Inject A a;
}
When constructing an instance of A, a naive injector implementation might go into an infinite loop constructing an instance of B to set on A, a second instance of A to set on B, a second instance of B to set on the second instance of A, and so on.
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 Provider<A> or
Provider<B> instead of A or B respectively. Calling 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 singleton scope, for example) may also enable a valid circular relationship.
See Also:
/**
* 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 {}