Debian Codegraph @

guava-testlib/src/com/google/common/collect/testing/features/FeatureUtil.java

raw
1 /*
2 * Copyright (C) 2008 The Guava Authors
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 com.google.common.collect.testing.features;
18
19 import com.google.common.annotations.GwtIncompatible;
20 import com.google.common.collect.testing.Helpers;
21 import com.google.errorprone.annotations.CanIgnoreReturnValue;
22 import java.lang.annotation.Annotation;
23 import java.lang.reflect.AnnotatedElement;
24 import java.lang.reflect.Method;
25 import java.util.ArrayDeque;
26 import java.util.ArrayList;
27 import java.util.Collections;
28 import java.util.HashMap;
29 import java.util.LinkedHashSet;
30 import java.util.List;
31 import java.util.Locale;
32 import java.util.Map;
33 import java.util.Queue;
34 import java.util.Set;
35
36 /**
37 * Utilities for collecting and validating tester requirements from annotations.
38 *
39 * @author George van den Driessche
40 */
41 @GwtIncompatible
42 public class FeatureUtil {
43 /** A cache of annotated objects (typically a Class or Method) to its set of annotations. */
44 private static Map<AnnotatedElement, List<Annotation>> annotationCache = new HashMap<>();
45
46 private static final Map<Class<?>, TesterRequirements> classTesterRequirementsCache =
47 new HashMap<>();
48
49 private static final Map<Method, TesterRequirements> methodTesterRequirementsCache =
50 new HashMap<>();
51
52 /**
53 * Given a set of features, add to it all the features directly or indirectly implied by any of
54 * them, and return it.
55 *
56 * @param features the set of features to expand
57 * @return the same set of features, expanded with all implied features
58 */
59 @CanIgnoreReturnValue
60 public static Set<Feature<?>> addImpliedFeatures(Set<Feature<?>> features) {
61 Queue<Feature<?>> queue = new ArrayDeque<>(features);
62 while (!queue.isEmpty()) {
63 Feature<?> feature = queue.remove();
64 for (Feature<?> implied : feature.getImpliedFeatures()) {
65 if (features.add(implied)) {
66 queue.add(implied);
67 }
68 }
69 }
70 return features;
71 }
72
73 /**
74 * Given a set of features, return a new set of all features directly or indirectly implied by any
75 * of them.
76 *
77 * @param features the set of features whose implications to find
78 * @return the implied set of features
79 */
80 public static Set<Feature<?>> impliedFeatures(Set<Feature<?>> features) {
81 Set<Feature<?>> impliedSet = new LinkedHashSet<>();
82 Queue<Feature<?>> queue = new ArrayDeque<>(features);
83 while (!queue.isEmpty()) {
84 Feature<?> feature = queue.remove();
85 for (Feature<?> implied : feature.getImpliedFeatures()) {
86 if (!features.contains(implied) && impliedSet.add(implied)) {
87 queue.add(implied);
88 }
89 }
90 }
91 return impliedSet;
92 }
93
94 /**
95 * Get the full set of requirements for a tester class.
96 *
97 * @param testerClass a tester class
98 * @return all the constraints implicitly or explicitly required by the class or any of its
99 * superclasses.
100 * @throws ConflictingRequirementsException if the requirements are mutually inconsistent.
101 */
102 public static TesterRequirements getTesterRequirements(Class<?> testerClass)
103 throws ConflictingRequirementsException {
104 synchronized (classTesterRequirementsCache) {
105 TesterRequirements requirements = classTesterRequirementsCache.get(testerClass);
106 if (requirements == null) {
107 requirements = buildTesterRequirements(testerClass);
108 classTesterRequirementsCache.put(testerClass, requirements);
109 }
110 return requirements;
111 }
112 }
113
114 /**
115 * Get the full set of requirements for a tester class.
116 *
117 * @param testerMethod a test method of a tester class
118 * @return all the constraints implicitly or explicitly required by the method, its declaring
119 * class, or any of its superclasses.
120 * @throws ConflictingRequirementsException if the requirements are mutually inconsistent.
121 */
122 public static TesterRequirements getTesterRequirements(Method testerMethod)
123 throws ConflictingRequirementsException {
124 synchronized (methodTesterRequirementsCache) {
125 TesterRequirements requirements = methodTesterRequirementsCache.get(testerMethod);
126 if (requirements == null) {
127 requirements = buildTesterRequirements(testerMethod);
128 methodTesterRequirementsCache.put(testerMethod, requirements);
129 }
130 return requirements;
131 }
132 }
133
134 /**
135 * Construct the full set of requirements for a tester class.
136 *
137 * @param testerClass a tester class
138 * @return all the constraints implicitly or explicitly required by the class or any of its
139 * superclasses.
140 * @throws ConflictingRequirementsException if the requirements are mutually inconsistent.
141 */
142 static TesterRequirements buildTesterRequirements(Class<?> testerClass)
143 throws ConflictingRequirementsException {
144 TesterRequirements declaredRequirements = buildDeclaredTesterRequirements(testerClass);
145 Class<?> baseClass = testerClass.getSuperclass();
146 if (baseClass == null) {
147 return declaredRequirements;
148 } else {
149 TesterRequirements clonedBaseRequirements =
150 new TesterRequirements(getTesterRequirements(baseClass));
151 return incorporateRequirements(clonedBaseRequirements, declaredRequirements, testerClass);
152 }
153 }
154
155 /**
156 * Construct the full set of requirements for a tester method.
157 *
158 * @param testerMethod a test method of a tester class
159 * @return all the constraints implicitly or explicitly required by the method, its declaring
160 * class, or any of its superclasses.
161 * @throws ConflictingRequirementsException if the requirements are mutually inconsistent.
162 */
163 static TesterRequirements buildTesterRequirements(Method testerMethod)
164 throws ConflictingRequirementsException {
165 TesterRequirements clonedClassRequirements =
166 new TesterRequirements(getTesterRequirements(testerMethod.getDeclaringClass()));
167 TesterRequirements declaredRequirements = buildDeclaredTesterRequirements(testerMethod);
168 return incorporateRequirements(clonedClassRequirements, declaredRequirements, testerMethod);
169 }
170
171 /**
172 * Find all the constraints explicitly or implicitly specified by a single tester annotation.
173 *
174 * @param testerAnnotation a tester annotation
175 * @return the requirements specified by the annotation
176 * @throws ConflictingRequirementsException if the requirements are mutually inconsistent.
177 */
178 private static TesterRequirements buildTesterRequirements(Annotation testerAnnotation)
179 throws ConflictingRequirementsException {
180 Class<? extends Annotation> annotationClass = testerAnnotation.annotationType();
181 Feature<?>[] presentFeatures;
182 Feature<?>[] absentFeatures;
183 try {
184 presentFeatures = (Feature[]) annotationClass.getMethod("value").invoke(testerAnnotation);
185 absentFeatures = (Feature[]) annotationClass.getMethod("absent").invoke(testerAnnotation);
186 } catch (Exception e) {
187 throw new IllegalArgumentException("Error extracting features from tester annotation.", e);
188 }
189 Set<Feature<?>> allPresentFeatures =
190 addImpliedFeatures(Helpers.<Feature<?>>copyToSet(presentFeatures));
191 Set<Feature<?>> allAbsentFeatures =
192 addImpliedFeatures(Helpers.<Feature<?>>copyToSet(absentFeatures));
193 if (!Collections.disjoint(allPresentFeatures, allAbsentFeatures)) {
194 throw new ConflictingRequirementsException(
195 "Annotation explicitly or "
196 + "implicitly requires one or more features to be both present "
197 + "and absent.",
198 intersection(allPresentFeatures, allAbsentFeatures),
199 testerAnnotation);
200 }
201 return new TesterRequirements(allPresentFeatures, allAbsentFeatures);
202 }
203
204 /**
205 * Construct the set of requirements specified by annotations directly on a tester class or
206 * method.
207 *
208 * @param classOrMethod a tester class or a test method thereof
209 * @return all the constraints implicitly or explicitly required by annotations on the class or
210 * method.
211 * @throws ConflictingRequirementsException if the requirements are mutually inconsistent.
212 */
213 public static TesterRequirements buildDeclaredTesterRequirements(AnnotatedElement classOrMethod)
214 throws ConflictingRequirementsException {
215 TesterRequirements requirements = new TesterRequirements();
216
217 Iterable<Annotation> testerAnnotations = getTesterAnnotations(classOrMethod);
218 for (Annotation testerAnnotation : testerAnnotations) {
219 TesterRequirements moreRequirements = buildTesterRequirements(testerAnnotation);
220 incorporateRequirements(requirements, moreRequirements, testerAnnotation);
221 }
222
223 return requirements;
224 }
225
226 /**
227 * Find all the tester annotations declared on a tester class or method.
228 *
229 * @param classOrMethod a class or method whose tester annotations to find
230 * @return an iterable sequence of tester annotations on the class
231 */
232 public static Iterable<Annotation> getTesterAnnotations(AnnotatedElement classOrMethod) {
233 synchronized (annotationCache) {
234 List<Annotation> annotations = annotationCache.get(classOrMethod);
235 if (annotations == null) {
236 annotations = new ArrayList<>();
237 for (Annotation a : classOrMethod.getDeclaredAnnotations()) {
238 if (a.annotationType().isAnnotationPresent(TesterAnnotation.class)) {
239 annotations.add(a);
240 }
241 }
242 annotations = Collections.unmodifiableList(annotations);
243 annotationCache.put(classOrMethod, annotations);
244 }
245 return annotations;
246 }
247 }
248
249 /**
250 * Incorporate additional requirements into an existing requirements object.
251 *
252 * @param requirements the existing requirements object
253 * @param moreRequirements more requirements to incorporate
254 * @param source the source of the additional requirements (used only for error reporting)
255 * @return the existing requirements object, modified to include the additional requirements
256 * @throws ConflictingRequirementsException if the additional requirements are inconsistent with
257 * the existing requirements
258 */
259 @CanIgnoreReturnValue
260 private static TesterRequirements incorporateRequirements(
261 TesterRequirements requirements, TesterRequirements moreRequirements, Object source)
262 throws ConflictingRequirementsException {
263 Set<Feature<?>> presentFeatures = requirements.getPresentFeatures();
264 Set<Feature<?>> absentFeatures = requirements.getAbsentFeatures();
265 Set<Feature<?>> morePresentFeatures = moreRequirements.getPresentFeatures();
266 Set<Feature<?>> moreAbsentFeatures = moreRequirements.getAbsentFeatures();
267 checkConflict("absent", absentFeatures, "present", morePresentFeatures, source);
268 checkConflict("present", presentFeatures, "absent", moreAbsentFeatures, source);
269 presentFeatures.addAll(morePresentFeatures);
270 absentFeatures.addAll(moreAbsentFeatures);
271 return requirements;
272 }
273
274 // Used by incorporateRequirements() only
275 private static void checkConflict(
276 String earlierRequirement,
277 Set<Feature<?>> earlierFeatures,
278 String newRequirement,
279 Set<Feature<?>> newFeatures,
280 Object source)
281 throws ConflictingRequirementsException {
282 if (!Collections.disjoint(newFeatures, earlierFeatures)) {
283 throw new ConflictingRequirementsException(
284 String.format(
285 Locale.ROOT,
286 "Annotation requires to be %s features that earlier "
287 + "annotations required to be %s.",
288 newRequirement,
289 earlierRequirement),
290 intersection(newFeatures, earlierFeatures),
291 source);
292 }
293 }
294
295 /** Construct a new {@link java.util.Set} that is the intersection of the given sets. */
296 public static <T> Set<T> intersection(Set<? extends T> set1, Set<? extends T> set2) {
297 Set<T> result = Helpers.<T>copyToSet(set1);
298 result.retainAll(set2);
299 return result;
300 }
301 }