Provide access to source element annotations for TempDirFactory · junit-team/junit-framework@acb6e65 (original) (raw)
``
1
`+
/*
`
``
2
`+
- Copyright 2015-2023 the original author or authors.
`
``
3
`+
`
``
4
`+
- All rights reserved. This program and the accompanying materials are
`
``
5
`+
- made available under the terms of the Eclipse Public License v2.0 which
`
``
6
`+
- accompanies this distribution and is available at
`
``
7
`+
`
``
8
`+
`
``
9
`+
*/
`
``
10
+
``
11
`+
package org.junit.jupiter.api.extension;
`
``
12
+
``
13
`+
import static org.apiguardian.api.API.Status.EXPERIMENTAL;
`
``
14
+
``
15
`+
import java.lang.annotation.Annotation;
`
``
16
`+
import java.lang.reflect.AnnotatedElement;
`
``
17
`+
import java.util.List;
`
``
18
`+
import java.util.Optional;
`
``
19
+
``
20
`+
import org.apiguardian.api.API;
`
``
21
`+
import org.junit.platform.commons.support.AnnotationSupport;
`
``
22
+
``
23
`+
/**
`
``
24
`+
- {@code AnnotatedElementContext} encapsulates the context in which an
`
``
25
`+
- {@link #getAnnotatedElement() AnnotatedElement} is declared.
`
``
26
`+
`
``
27
`+
For example, an {@code AnnotatedElementContext} is used in
`
``
28
`+
- {@link org.junit.jupiter.api.io.TempDirFactory TempDirFactory} to allow inspecting
`
``
29
`+
- the field or parameter the {@link org.junit.jupiter.api.io.TempDir TempDir}
`
``
30
`+
- annotation is declared on.
`
``
31
`+
`
``
32
`+
This interface is not intended to be implemented by clients.
`
``
33
`+
`
``
34
`+
- @since 5.10
`
``
35
`+
*/
`
``
36
`+
@API(status = EXPERIMENTAL, since = "5.10")
`
``
37
`+
public interface AnnotatedElementContext {
`
``
38
+
``
39
`+
/**
`
``
40
`+
- Get the {@link AnnotatedElement} for this context.
`
``
41
`+
`
``
42
`+
WARNING
`
``
43
`+
When searching for annotations on the annotated element in this context,
`
``
44
`+
- favor {@link #isAnnotated(Class)}, {@link #findAnnotation(Class)}, and
`
``
45
`+
- {@link #findRepeatableAnnotations(Class)} over methods in the
`
``
46
`+
- {@link AnnotatedElement} API due to a bug in {@code javac} on JDK versions prior
`
``
47
`+
- to JDK 9.
`
``
48
`+
`
``
49
`+
- @return the annotated element; never {@code null}
`
``
50
`+
*/
`
``
51
`+
AnnotatedElement getAnnotatedElement();
`
``
52
+
``
53
`+
/**
`
``
54
`+
- Determine if an annotation of {@code annotationType} is either
`
``
55
`+
- present or meta-present on the {@link AnnotatedElement} for
`
``
56
`+
- this context.
`
``
57
`+
`
``
58
`+
WARNING
`
``
59
`+
Favor the use of this method over directly invoking
`
``
60
`+
- {@link AnnotatedElement#isAnnotationPresent(Class)} due to a bug in {@code javac}
`
``
61
`+
- on JDK versions prior to JDK 9.
`
``
62
`+
`
``
63
`+
- @param annotationType the annotation type to search for; never {@code null}
`
``
64
`+
- @return {@code true} if the annotation is present or meta-present
`
``
65
`+
- @see #findAnnotation(Class)
`
``
66
`+
- @see #findRepeatableAnnotations(Class)
`
``
67
`+
*/
`
``
68
`+
default boolean isAnnotated(Class<? extends Annotation> annotationType) {
`
``
69
`+
return AnnotationSupport.isAnnotated(getAnnotatedElement(), annotationType);
`
``
70
`+
}
`
``
71
+
``
72
`+
/**
`
``
73
`+
- Find the first annotation of {@code annotationType} that is either
`
``
74
`+
- present or meta-present on the {@link AnnotatedElement} for
`
``
75
`+
- this context.
`
``
76
`+
`
``
77
`+
WARNING
`
``
78
`+
Favor the use of this method over directly invoking annotation lookup
`
``
79
`+
- methods in the {@link AnnotatedElement} API due to a bug in {@code javac} on JDK
`
``
80
`+
- versions prior to JDK 9.
`
``
81
`+
`
``
82
`+
- @param the annotation type
`
``
83
`+
- @param annotationType the annotation type to search for; never {@code null}
`
``
84
`+
- @return an {@code Optional} containing the annotation; never {@code null} but
`
``
85
`+
- potentially empty
`
``
86
`+
- @see #isAnnotated(Class)
`
``
87
`+
- @see #findRepeatableAnnotations(Class)
`
``
88
`+
*/
`
``
89
`+
default Optional findAnnotation(Class annotationType) {
`
``
90
`+
return AnnotationSupport.findAnnotation(getAnnotatedElement(), annotationType);
`
``
91
`+
}
`
``
92
+
``
93
`+
/**
`
``
94
`+
- Find all repeatable {@linkplain Annotation annotations} of
`
``
95
`+
- {@code annotationType} that are either present or
`
``
96
`+
- meta-present on the {@link AnnotatedElement} for this context.
`
``
97
`+
`
``
98
`+
WARNING
`
``
99
`+
Favor the use of this method over directly invoking annotation lookup
`
``
100
`+
- methods in the {@link AnnotatedElement} API due to a bug in {@code javac} on JDK
`
``
101
`+
- versions prior to JDK 9.
`
``
102
`+
`
``
103
`+
- @param the annotation type
`
``
104
`+
- @param annotationType the repeatable annotation type to search for; never
`
``
105
`+
- {@code null}
`
``
106
`+
- @return the list of all such annotations found; neither {@code null} nor
`
``
107
`+
- mutable, but potentially empty
`
``
108
`+
- @see #isAnnotated(Class)
`
``
109
`+
- @see #findAnnotation(Class)
`
``
110
`+
- @see java.lang.annotation.Repeatable
`
``
111
`+
*/
`
``
112
`+
default List findRepeatableAnnotations(Class annotationType) {
`
``
113
`+
return AnnotationSupport.findRepeatableAnnotations(getAnnotatedElement(), annotationType);
`
``
114
`+
}
`
``
115
+
``
116
`+
}
`