author | darcy |
Wed, 01 May 2019 16:47:26 -0700 | |
changeset 54673 | 67b040623a12 |
parent 53201 | 28ec06beb091 |
permissions | -rw-r--r-- |
10 | 1 |
/* |
53201
28ec06beb091
8216335: Minor cleanups to javax.annotation.processing and javax.lang.model javadoc
darcy
parents:
47216
diff
changeset
|
2 |
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved. |
10 | 3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 |
* |
|
5 |
* This code is free software; you can redistribute it and/or modify it |
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
|
5520 | 7 |
* published by the Free Software Foundation. Oracle designates this |
10 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5520 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
10 | 10 |
* |
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
|
15 |
* accompanied this code). |
|
16 |
* |
|
17 |
* You should have received a copy of the GNU General Public License version |
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
* |
|
5520 | 21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
* or visit www.oracle.com if you need additional information or have any |
|
23 |
* questions. |
|
10 | 24 |
*/ |
25 |
||
26 |
package javax.annotation.processing; |
|
27 |
||
54673
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
28 |
import java.util.List; |
10 | 29 |
import java.util.Set; |
30 |
import java.util.HashSet; |
|
31 |
import java.util.Collections; |
|
16795
04f5c8373776
7041251: Use j.u.Objects utility methods in langtools
darcy
parents:
5520
diff
changeset
|
32 |
import java.util.Objects; |
10 | 33 |
import javax.lang.model.element.*; |
34 |
import javax.lang.model.SourceVersion; |
|
35 |
import javax.tools.Diagnostic; |
|
36 |
||
37 |
/** |
|
38 |
* An abstract annotation processor designed to be a convenient |
|
39 |
* superclass for most concrete annotation processors. This class |
|
40 |
* examines annotation values to compute the {@linkplain |
|
41 |
* #getSupportedOptions options}, {@linkplain |
|
18669
99572d59c916
7162089: Add support for repeating annotations to javax.annotation.processing
darcy
parents:
16795
diff
changeset
|
42 |
* #getSupportedAnnotationTypes annotation types}, and {@linkplain |
10 | 43 |
* #getSupportedSourceVersion source version} supported by its |
44 |
* subtypes. |
|
45 |
* |
|
46 |
* <p>The getter methods may {@linkplain Messager#printMessage issue |
|
47 |
* warnings} about noteworthy conditions using the facilities available |
|
48 |
* after the processor has been {@linkplain #isInitialized |
|
49 |
* initialized}. |
|
50 |
* |
|
51 |
* <p>Subclasses are free to override the implementation and |
|
52 |
* specification of any of the methods in this class as long as the |
|
53 |
* general {@link javax.annotation.processing.Processor Processor} |
|
54 |
* contract for that method is obeyed. |
|
55 |
* |
|
56 |
* @author Joseph D. Darcy |
|
57 |
* @author Scott Seligman |
|
58 |
* @author Peter von der Ahé |
|
59 |
* @since 1.6 |
|
60 |
*/ |
|
61 |
public abstract class AbstractProcessor implements Processor { |
|
62 |
/** |
|
63 |
* Processing environment providing by the tool framework. |
|
64 |
*/ |
|
65 |
protected ProcessingEnvironment processingEnv; |
|
66 |
private boolean initialized = false; |
|
67 |
||
68 |
/** |
|
69 |
* Constructor for subclasses to call. |
|
70 |
*/ |
|
71 |
protected AbstractProcessor() {} |
|
72 |
||
73 |
/** |
|
74 |
* If the processor class is annotated with {@link |
|
75 |
* SupportedOptions}, return an unmodifiable set with the same set |
|
76 |
* of strings as the annotation. If the class is not so |
|
77 |
* annotated, an empty set is returned. |
|
78 |
* |
|
79 |
* @return the options recognized by this processor, or an empty |
|
80 |
* set if none |
|
81 |
*/ |
|
82 |
public Set<String> getSupportedOptions() { |
|
83 |
SupportedOptions so = this.getClass().getAnnotation(SupportedOptions.class); |
|
54673
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
84 |
return (so == null) ? |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
85 |
Set.of() : |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
86 |
arrayToSet(so.value(), false, "option value", "@SupportedOptions"); |
10 | 87 |
} |
88 |
||
89 |
/** |
|
90 |
* If the processor class is annotated with {@link |
|
91 |
* SupportedAnnotationTypes}, return an unmodifiable set with the |
|
92 |
* same set of strings as the annotation. If the class is not so |
|
93 |
* annotated, an empty set is returned. |
|
94 |
* |
|
53201
28ec06beb091
8216335: Minor cleanups to javax.annotation.processing and javax.lang.model javadoc
darcy
parents:
47216
diff
changeset
|
95 |
* If the {@linkplain ProcessingEnvironment#getSourceVersion source |
43585
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
96 |
* version} does not support modules, in other words if it is less |
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
97 |
* than or equal to {@link SourceVersion#RELEASE_8 RELEASE_8}, |
53201
28ec06beb091
8216335: Minor cleanups to javax.annotation.processing and javax.lang.model javadoc
darcy
parents:
47216
diff
changeset
|
98 |
* then any leading {@linkplain Processor#getSupportedAnnotationTypes |
43585
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
99 |
* module prefixes} are stripped from the names. |
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
100 |
* |
10 | 101 |
* @return the names of the annotation types supported by this |
102 |
* processor, or an empty set if none |
|
103 |
*/ |
|
104 |
public Set<String> getSupportedAnnotationTypes() { |
|
105 |
SupportedAnnotationTypes sat = this.getClass().getAnnotation(SupportedAnnotationTypes.class); |
|
43585
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
106 |
boolean initialized = isInitialized(); |
10 | 107 |
if (sat == null) { |
43585
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
108 |
if (initialized) |
10 | 109 |
processingEnv.getMessager().printMessage(Diagnostic.Kind.WARNING, |
110 |
"No SupportedAnnotationTypes annotation " + |
|
111 |
"found on " + this.getClass().getName() + |
|
112 |
", returning an empty set."); |
|
54673
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
113 |
return Set.of(); |
43585
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
114 |
} else { |
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
115 |
boolean stripModulePrefixes = |
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
116 |
initialized && |
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
117 |
processingEnv.getSourceVersion().compareTo(SourceVersion.RELEASE_8) <= 0; |
54673
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
118 |
return arrayToSet(sat.value(), stripModulePrefixes, |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
119 |
"annotation type", "@SupportedAnnotationTypes"); |
10 | 120 |
} |
121 |
} |
|
122 |
||
123 |
/** |
|
124 |
* If the processor class is annotated with {@link |
|
125 |
* SupportedSourceVersion}, return the source version in the |
|
126 |
* annotation. If the class is not so annotated, {@link |
|
127 |
* SourceVersion#RELEASE_6} is returned. |
|
128 |
* |
|
129 |
* @return the latest source version supported by this processor |
|
130 |
*/ |
|
131 |
public SourceVersion getSupportedSourceVersion() { |
|
132 |
SupportedSourceVersion ssv = this.getClass().getAnnotation(SupportedSourceVersion.class); |
|
133 |
SourceVersion sv = null; |
|
134 |
if (ssv == null) { |
|
135 |
sv = SourceVersion.RELEASE_6; |
|
136 |
if (isInitialized()) |
|
137 |
processingEnv.getMessager().printMessage(Diagnostic.Kind.WARNING, |
|
138 |
"No SupportedSourceVersion annotation " + |
|
139 |
"found on " + this.getClass().getName() + |
|
140 |
", returning " + sv + "."); |
|
141 |
} else |
|
142 |
sv = ssv.value(); |
|
143 |
return sv; |
|
144 |
} |
|
145 |
||
146 |
||
147 |
/** |
|
148 |
* Initializes the processor with the processing environment by |
|
149 |
* setting the {@code processingEnv} field to the value of the |
|
150 |
* {@code processingEnv} argument. An {@code |
|
151 |
* IllegalStateException} will be thrown if this method is called |
|
152 |
* more than once on the same object. |
|
153 |
* |
|
154 |
* @param processingEnv environment to access facilities the tool framework |
|
155 |
* provides to the processor |
|
156 |
* @throws IllegalStateException if this method is called more than once. |
|
157 |
*/ |
|
158 |
public synchronized void init(ProcessingEnvironment processingEnv) { |
|
159 |
if (initialized) |
|
160 |
throw new IllegalStateException("Cannot call init more than once."); |
|
16795
04f5c8373776
7041251: Use j.u.Objects utility methods in langtools
darcy
parents:
5520
diff
changeset
|
161 |
Objects.requireNonNull(processingEnv, "Tool provided null ProcessingEnvironment"); |
10 | 162 |
|
163 |
this.processingEnv = processingEnv; |
|
164 |
initialized = true; |
|
165 |
} |
|
166 |
||
167 |
/** |
|
168 |
* {@inheritDoc} |
|
169 |
*/ |
|
170 |
public abstract boolean process(Set<? extends TypeElement> annotations, |
|
171 |
RoundEnvironment roundEnv); |
|
172 |
||
173 |
/** |
|
174 |
* Returns an empty iterable of completions. |
|
175 |
* |
|
176 |
* @param element {@inheritDoc} |
|
177 |
* @param annotation {@inheritDoc} |
|
178 |
* @param member {@inheritDoc} |
|
179 |
* @param userText {@inheritDoc} |
|
180 |
*/ |
|
181 |
public Iterable<? extends Completion> getCompletions(Element element, |
|
182 |
AnnotationMirror annotation, |
|
183 |
ExecutableElement member, |
|
184 |
String userText) { |
|
54673
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
185 |
return List.of(); |
10 | 186 |
} |
187 |
||
188 |
/** |
|
189 |
* Returns {@code true} if this object has been {@linkplain #init |
|
190 |
* initialized}, {@code false} otherwise. |
|
191 |
* |
|
192 |
* @return {@code true} if this object has been initialized, |
|
193 |
* {@code false} otherwise. |
|
194 |
*/ |
|
195 |
protected synchronized boolean isInitialized() { |
|
196 |
return initialized; |
|
197 |
} |
|
198 |
||
54673
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
199 |
private Set<String> arrayToSet(String[] array, |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
200 |
boolean stripModulePrefixes, |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
201 |
String contentType, |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
202 |
String annotationName) { |
10 | 203 |
assert array != null; |
54673
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
204 |
Set<String> set = new HashSet<>(); |
43585
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
205 |
for (String s : array) { |
54673
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
206 |
boolean stripped = false; |
43585
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
207 |
if (stripModulePrefixes) { |
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
208 |
int index = s.indexOf('/'); |
54673
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
209 |
if (index != -1) { |
43585
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
210 |
s = s.substring(index + 1); |
54673
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
211 |
stripped = true; |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
212 |
} |
43585
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
213 |
} |
54673
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
214 |
boolean added = set.add(s); |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
215 |
// Don't issue a duplicate warning when the module name is |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
216 |
// stripped off to avoid spurious warnings in a case like |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
217 |
// "foo/a.B", "bar/a.B". |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
218 |
if (!added && !stripped && isInitialized() ) { |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
219 |
processingEnv.getMessager().printMessage(Diagnostic.Kind.WARNING, |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
220 |
"Duplicate " + contentType + |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
221 |
" ``" + s + "'' for processor " + |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
222 |
this.getClass().getName() + |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
223 |
" in its " + annotationName + |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
224 |
"annotation."); |
67b040623a12
8146726: Improve AbstractProcessor to issue warnings for repeated information
darcy
parents:
53201
diff
changeset
|
225 |
} |
43585
19e14d35add0
8173636: Results from Processor.getSupportedAnnotationTypes should be intepreted strictly
jlahoda
parents:
25874
diff
changeset
|
226 |
} |
10 | 227 |
return Collections.unmodifiableSet(set); |
228 |
} |
|
229 |
} |