guava

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
}
302