javax.inject.Inject Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of javaee-api Show documentation
The newest version!
/*
 * 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 {@code @Inject} and accept
 * zero or more dependencies as arguments. {@code @Inject} can apply to at most
 * one constructor per class.
 *
 * 
@Inject
 *       ConstructorModifiers_opt
 *       SimpleTypeName(FormalParameterList_opt)
 *       Throws_opt
 *       ConstructorBody
 *
 * {@code @Inject} is optional for public, no-argument constructors when no
 * other constructors are present. This enables injectors to invoke default
 * constructors.
 *
 * 

 *       {@literal @}Inject_opt
 *       Annotations_opt
 *       public
 *       SimpleTypeName()
 *       Throws_opt
 *       ConstructorBody
 *
 * Injectable fields:
 * 

 *   are annotated with {@code @Inject}.
 *   
are not final.
 *   
may have any otherwise valid name.
 *
 * 
@Inject
 *       FieldModifiers_opt
 *       Type
 *       VariableDeclarators;
 *
 * Injectable methods:
 * 

 *   are annotated with {@code @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
 *       MethodModifiers_opt
 *       ResultType
 *       Identifier(FormalParameterList_opt)
 *       Throws_opt
 *       MethodBody
 *
 * 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).
 *
 * 
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 {@code @Inject} that overrides another method
 * annotated with {@code @Inject} will only be injected once per injection
 * request per instance. A method with no {@code @Inject} annotation
 * that overrides a method annotated with {@code @Inject} will not be
 * injected.
 *
 * 
Injection of members annotated with {@code @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 {@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:
 *
 * 
 *   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 {@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.
 *
 * 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} 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 {}