+Inject +

From d53f42e880ca05a483e68d88224c89b3f36bca43 Mon Sep 17 00:00:00 2001 From: Bob Lee Date: Tue, 13 Oct 2009 19:55:36 +0000 Subject: Uploaded final spec. git-svn-id: https://atinject.googlecode.com/svn/trunk@56 3bc8319c-20ab-11de-9edc-3f40a397ab60 --- javadoc/javax/inject/Inject.html | 317 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 317 insertions(+) create mode 100644 javadoc/javax/inject/Inject.html (limited to 'javadoc/javax/inject/Inject.html') diff --git a/javadoc/javax/inject/Inject.html b/javadoc/javax/inject/Inject.html new file mode 100644 index 0000000..061999e --- /dev/null +++ b/javadoc/javax/inject/Inject.html @@ -0,0 +1,317 @@ + + + + + + +Inject + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

Package

Class

Tree

Deprecated

Index

Help

+ +

+ PREV CLASS + NEXT CLASS

+ FRAMES + NO FRAMES + + + + +

+ SUMMARY: REQUIRED | OPTIONAL

+DETAIL: ELEMENT

+ + + +

+ +

+ +javax.inject +
+Annotation Type Inject

@Target(value={METHOD,CONSTRUCTOR,FIELD}) +@Retention(value=RUNTIME) +@Documented +public @interface Inject

+ + +

+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 + ConstructorModifiers_opt + SimpleTypeName(FormalParameterList_opt) + Throws_opt + ConstructorBody

+ +

@Inject is optional for public, no-argument constructors when no + other constructors are present. This enables injectors to invoke default + constructors. + +

+ @Inject_opt + Annotations_opt + public + SimpleTypeName() + Throws_opt + ConstructorBody

+ +

Injectable fields: +

are annotated with @Inject. +
are not final. +
may have any otherwise valid name.

+ +

@Inject + FieldModifiers_opt + 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 + MethodModifiers_opt + ResultType + Identifier(FormalParameterList_opt) + Throws_opt + 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:: @Qualifier, +Provider

+ +

+ + + + + + + + + + + + + + + + + + + +