1 /* 2 * Copyright (C) 2009 The JSR-330 Expert Group 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package javax.inject; 18 19 import java.lang.annotation.Target; 20 import java.lang.annotation.Retention; 21 import java.lang.annotation.Documented; 22 import static java.lang.annotation.RetentionPolicy.RUNTIME; 23 import static java.lang.annotation.ElementType.METHOD; 24 import static java.lang.annotation.ElementType.CONSTRUCTOR; 25 import static java.lang.annotation.ElementType.FIELD; 26 27 /** 28 * Identifies injectable constructors, methods, and fields. May apply to static 29 * as well as instance members. An injectable member may have any access 30 * modifier (private, package-private, protected, public). Constructors are 31 * injected first, followed by fields, and then methods. Fields and methods 32 * in superclasses are injected before those in subclasses. Ordering of 33 * injection among fields and among methods in the same class is not specified. 34 * 35 * <p>Injectable constructors are annotated with {@code @Inject} and accept 36 * zero or more dependencies as arguments. {@code @Inject} can apply to at most 37 * one constructor per class. 38 * 39 * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject 40 * <i>ConstructorModifiers<sub>opt</sub></i> 41 * <i>SimpleTypeName</i>(<i>FormalParameterList<sub>opt</sub></i>) 42 * <i>Throws<sub>opt</sub></i> 43 * <i>ConstructorBody</i></blockquote></tt> 44 * 45 * <p>{@code @Inject} is optional for public, no-argument constructors when no 46 * other constructors are present. This enables injectors to invoke default 47 * constructors. 48 * 49 * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;"> 50 * {@literal @}Inject<sub><i>opt</i></sub> 51 * <i>Annotations<sub>opt</sub></i> 52 * public 53 * <i>SimpleTypeName</i>() 54 * <i>Throws<sub>opt</sub></i> 55 * <i>ConstructorBody</i></blockquote></tt> 56 * 57 * <p>Injectable fields: 58 * <ul> 59 * <li>are annotated with {@code @Inject}. 60 * <li>are not final. 61 * <li>may have any otherwise valid name.</li></ul> 62 * 63 * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject 64 * <i>FieldModifiers<sub>opt</sub></i> 65 * <i>Type</i> 66 * <i>VariableDeclarators</i>;</blockquote></tt> 67 * 68 * <p>Injectable methods: 69 * <ul> 70 * <li>are annotated with {@code @Inject}.</li> 71 * <li>are not abstract.</li> 72 * <li>do not declare type parameters of their own.</li> 73 * <li>may return a result</li> 74 * <li>may have any otherwise valid name.</li> 75 * <li>accept zero or more dependencies as arguments.</li></ul> 76 * 77 * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject 78 * <i>MethodModifiers<sub>opt</sub></i> 79 * <i>ResultType</i> 80 * <i>Identifier</i>(<i>FormalParameterList<sub>opt</sub></i>) 81 * <i>Throws<sub>opt</sub></i> 82 * <i>MethodBody</i></blockquote></tt> 83 * 84 * <p>The injector ignores the result of an injected method, but 85 * non-{@code void} return types are allowed to support use of the method in 86 * other contexts (builder-style method chaining, for example). 87 * 88 * <p>Examples: 89 * 90 * <pre> 91 * public class Car { 92 * // Injectable constructor 93 * @Inject public Car(Engine engine) { ... } 94 * 95 * // Injectable field 96 * @Inject private Provider<Seat> seatProvider; 97 * 98 * // Injectable package-private method 99 * @Inject void install(Windshield windshield, Trunk trunk) { ... } 100 * }</pre> 101 * 102 * <p>A method annotated with {@code @Inject} that overrides another method 103 * annotated with {@code @Inject} will only be injected once per injection 104 * request per instance. A method with <i>no</i> {@code @Inject} annotation 105 * that overrides a method annotated with {@code @Inject} will not be 106 * injected. 107 * 108 * <p>Injection of members annotated with {@code @Inject} is required. While an 109 * injectable member may use any accessibility modifier (including 110 * <tt>private</tt>), platform or injector limitations (like security 111 * restrictions or lack of reflection support) might preclude injection 112 * of non-public members. 113 * 114 * <h3>Qualifiers</h3> 115 * 116 * <p>A {@linkplain Qualifier qualifier} may annotate an injectable field 117 * or parameter and, combined with the type, identify the implementation to 118 * inject. Qualifiers are optional, and when used with {@code @Inject} in 119 * injector-independent classes, no more than one qualifier should annotate a 120 * single field or parameter. The qualifiers are bold in the following example: 121 * 122 * <pre> 123 * public class Car { 124 * @Inject private <b>@Leather</b> Provider<Seat> seatProvider; 125 * 126 * @Inject void install(<b>@Tinted</b> Windshield windshield, 127 * <b>@Big</b> Trunk trunk) { ... } 128 * }</pre> 129 * 130 * <p>If one injectable method overrides another, the overriding method's 131 * parameters do not automatically inherit qualifiers from the overridden 132 * method's parameters. 133 * 134 * <h3>Injectable Values</h3> 135 * 136 * <p>For a given type T and optional qualifier, an injector must be able to 137 * inject a user-specified class that: 138 * 139 * <ol type="a"> 140 * <li>is assignment compatible with T and</li> 141 * <li>has an injectable constructor.</li> 142 * </ol> 143 * 144 * <p>For example, the user might use external configuration to pick an 145 * implementation of T. Beyond that, which values are injected depend upon the 146 * injector implementation and its configuration. 147 * 148 * <h3>Circular Dependencies</h3> 149 * 150 * <p>Detecting and resolving circular dependencies is left as an exercise for 151 * the injector implementation. Circular dependencies between two constructors 152 * is an obvious problem, but you can also have a circular dependency between 153 * injectable fields or methods: 154 * 155 * <pre> 156 * class A { 157 * @Inject B b; 158 * } 159 * class B { 160 * @Inject A a; 161 * }</pre> 162 * 163 * <p>When constructing an instance of {@code A}, a naive injector 164 * implementation might go into an infinite loop constructing an instance of 165 * {@code B} to set on {@code A}, a second instance of {@code A} to set on 166 * {@code B}, a second instance of {@code B} to set on the second instance of 167 * {@code A}, and so on. 168 * 169 * <p>A conservative injector might detect the circular dependency at build 170 * time and generate an error, at which point the programmer could break the 171 * circular dependency by injecting {@link Provider Provider<A>} or {@code 172 * Provider<B>} instead of {@code A} or {@code B} respectively. Calling {@link 173 * Provider#get() get()} on the provider directly from the constructor or 174 * method it was injected into defeats the provider's ability to break up 175 * circular dependencies. In the case of method or field injection, scoping 176 * one of the dependencies (using {@linkplain Singleton singleton scope}, for 177 * example) may also enable a valid circular relationship. 178 * 179 * @see javax.inject.Qualifier @Qualifier 180 * @see javax.inject.Provider 181 */ 182 @Target({ METHOD, CONSTRUCTOR, FIELD }) 183 @Retention(RUNTIME) 184 @Documented 185 public @interface Inject {} 186