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.ANNOTATION_TYPE; 24 25 /** 26 * Identifies scope annotations. A scope annotation applies to a class 27 * containing an injectable constructor and governs how the injector reuses 28 * instances of the type. By default, if no scope annotation is present, the 29 * injector creates an instance (by injecting the type's constructor), uses 30 * the instance for one injection, and then forgets it. If a scope annotation 31 * is present, the injector may retain the instance for possible reuse in a 32 * later injection. If multiple threads can access a scoped instance, its 33 * implementation should be thread safe. The implementation of the scope 34 * itself is left up to the injector. 35 * 36 * <p>In the following example, the scope annotation {@code @Singleton} ensures 37 * that we only have one Log instance: 38 * 39 * <pre> 40 * @Singleton 41 * class Log { 42 * void log(String message) { ... } 43 * }</pre> 44 * 45 * <p>The injector generates an error if it encounters more than one scope 46 * annotation on the same class or a scope annotation it doesn't support. 47 * 48 * <p>A scope annotation: 49 * <ul> 50 * <li>is annotated with {@code @Scope}, {@code @Retention(RUNTIME)}, 51 * and typically {@code @Documented}.</li> 52 * <li>should not have attributes.</li> 53 * <li>is typically not {@code @Inherited}, so scoping is orthogonal to 54 * implementation inheritance.</li> 55 * <li>may have restricted usage if annotated with {@code @Target}. While 56 * this specification covers applying scopes to classes only, some 57 * injector configurations might use scope annotations 58 * in other places (on factory method results for example).</li> 59 * </ul> 60 * 61 * <p>For example: 62 * 63 * <pre> 64 * @java.lang.annotation.Documented 65 * @java.lang.annotation.Retention(RUNTIME) 66 * @javax.inject.Scope 67 * public @interface RequestScoped {}</pre> 68 * 69 * <p>Annotating scope annotations with {@code @Scope} helps the injector 70 * detect the case where a programmer used the scope annotation on a class but 71 * forgot to configure the scope in the injector. A conservative injector 72 * would generate an error rather than not apply a scope. 73 * 74 * @see javax.inject.Singleton @Singleton 75 */ 76 @Target(ANNOTATION_TYPE) 77 @Retention(RUNTIME) 78 @Documented 79 public @interface Scope {} 80