diff options
Diffstat (limited to 'src/javax/inject/Scope.java')
-rw-r--r-- | src/javax/inject/Scope.java | 63 |
1 files changed, 63 insertions, 0 deletions
diff --git a/src/javax/inject/Scope.java b/src/javax/inject/Scope.java new file mode 100644 index 0000000..7eb2666 --- /dev/null +++ b/src/javax/inject/Scope.java @@ -0,0 +1,63 @@ +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.ANNOTATION_TYPE; + +/** + * Identifies scope annotations. A scope annotation applies to a class + * containing an injectable constructor and governs how the injector reuses + * instances of the type. By default, if no scope annotation is present, the + * injector creates an instance (by injecting the type's constructor), uses + * the instance for one injection, and then forgets it. If a scope annotation + * is present, the injector may retain the instance for possible reuse in a + * later injection. If multiple threads can access a scoped instance, its + * implementation should be thread safe. The implementation of the scope + * itself is left up to the injector. + * + * <p>In the following example, the scope annotation {@code @Singleton} ensures + * that we only have one Log instance: + * + * <pre> + * @Singleton + * class Log { + * void log(String message) { ... } + * }</pre> + * + * <p>The injector generates an error if it encounters more than one scope + * annotation on the same class or a scope annotation it doesn't support. + * + * <p>A scope annotation: + * <ul> + * <li>is annotated with {@code @Scope}, {@code @Retention(RUNTIME)}, + * and typically {@code @Documented}.</li> + * <li>should not have attributes.</li> + * <li>is typically not {@code @Inherited}, so scoping is orthogonal to + * implementation inheritance.</li> + * <li>is <i>not</i> annotated with {@code @Target}. While this + * specification only covers applying scopes to classes, some injector + * configurations might use scopes in other places (on factory + * method results for example).</li> + * </ul> + * + * <p>For example: + * + * <pre> + * @java.lang.annotation.Documented + * @java.lang.annotation.Retention(RUNTIME) + * @javax.inject.Scope + * public @interface RequestScoped {}</pre> + * + * <p>Annotating scope annotations with {@code @Scope} helps the injector + * detect the case where a programmer used the scope annotation on a class but + * forgot to configure the scope in the injector. A conservative injector + * would generate an error rather than not apply a scope. + * + * @see javax.inject.Singleton @Singleton + */ +@Target(ANNOTATION_TYPE) +@Retention(RUNTIME) +@Documented +public @interface Scope {} |