@Target(value={METHOD,CONSTRUCTOR,FIELD}) @Retention(value=RUNTIME) @Documented public @interface Inject
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:
@Inject
.
@Inject FieldModifiersopt Type VariableDeclarators;
Injectable methods:
@Inject
.@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.
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.
For a given type T and optional qualifier, an injector must be able to inject a user-specified class that:
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.
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.
@Qualifier
,
Provider
Comments to: cdi-dev@eclipse.org.
Copyright © 2018,2020 Eclipse Foundation.
Use is subject to license terms.