Debian Codegraph @

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/MetaAnnotations.java

raw
1 /*
2 * Copyright (c) 2021 Red Hat and others
3 *
4 * This program and the accompanying materials are made available under the
5 * Apache Software License 2.0 which is available at:
6 * https://www.apache.org/licenses/LICENSE-2.0.
7 *
8 * SPDX-License-Identifier: Apache-2.0
9 */
10
11 package jakarta.enterprise.inject.build.compatible.spi;
12
13 import jakarta.enterprise.context.spi.AlterableContext;
14
15 import java.lang.annotation.Annotation;
16 import java.util.function.Consumer;
17
18 /**
19 * Allows registering custom CDI meta-annotations: qualifiers, interceptor bindings,
20 * stereotypes, and scopes. When registering a custom scope, a context class must
21 * also be provided.
22 *
23 * @since 4.0
24 */
25 public interface MetaAnnotations {
26 /**
27 * Registers {@code annotation} as a qualifier annotation. Only makes sense if the annotation
28 * is not meta-annotated {@code @Qualifier}.
29 * <p>
30 * Returns a {@linkplain ClassConfig class configurator} object that allows transforming meta-annotations
31 * on the {@code annotation}.
32 *
33 * @param annotation annotation type
34 * @return the {@linkplain ClassConfig class configurator}, never {@code null}
35 */
36 ClassConfig addQualifier(Class<? extends Annotation> annotation);
37
38 /**
39 * Registers {@code annotation} as an interceptor binding annotation. Only makes sense if the annotation
40 * is not meta-annotated {@code @InterceptorBinding}.
41 * <p>
42 * Returns a {@linkplain ClassConfig class configurator} object that allows transforming meta-annotations
43 * on the {@code annotation}.
44 *
45 * @param annotation annotation type
46 * @return the {@linkplain ClassConfig class configurator}, never {@code null}
47 */
48 ClassConfig addInterceptorBinding(Class<? extends Annotation> annotation);
49
50 /**
51 * Registers {@code annotation} as a stereotype annotation. Only makes sense if the annotation
52 * is not meta-annotated {@code @Stereotype}.
53 * <p>
54 * Returns a {@linkplain ClassConfig class configurator} object that allows transforming meta-annotations
55 * on the {@code annotation}.
56 *
57 * @param annotation annotation type
58 * @return the {@linkplain ClassConfig class configurator}, never {@code null}
59 */
60 ClassConfig addStereotype(Class<? extends Annotation> annotation);
61
62 /**
63 * Registers custom context for given {@code scopeAnnotation} and given {@code contextClass}.
64 * CDI container will create an instance of the context class once to obtain the context object.
65 * The context class must be {@code public} and have a {@code public} zero-parameter constructor;
66 * it must not be a bean.
67 * <p>
68 * Whether the scope is normal is discovered from the scope annotation. This means that the scope
69 * annotation must be meta-annotated either {@link jakarta.enterprise.context.NormalScope @NormalScope}
70 * or {@link jakarta.inject.Scope @Scope}.
71 *
72 * @param scopeAnnotation the scope annotation type, must not be {@code null}
73 * @param contextClass the context class, must not be {@code null}
74 * @throws IllegalArgumentException if the {@code scopeAnnotation} is not meta-annotated {@code @NormalScope}
75 * or {@code @Scope}
76 */
77 void addContext(Class<? extends Annotation> scopeAnnotation, Class<? extends AlterableContext> contextClass);
78
79 /**
80 * Registers custom context for given {@code scopeAnnotation} and given {@code contextClass}.
81 * CDI container will create an instance of the context class once to obtain the context object.
82 * The context class must be {@code public} and have a {@code public} zero-parameter constructor;
83 * it must not be a bean.
84 * <p>
85 * The {@code isNormal} parameter determines whether the scope is a normal scope or a pseudo-scope.
86 *
87 * @param scopeAnnotation the scope annotation type, must not be {@code null}
88 * @param isNormal whether the scope is normal
89 * @param contextClass the context class, must not be {@code null}
90 */
91 void addContext(Class<? extends Annotation> scopeAnnotation, boolean isNormal, Class<? extends AlterableContext> contextClass);
92 }