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.GwtCompatible;
20 import com.google.common.collect.testing.Helpers;
21 import java.lang.annotation.Inherited;
22 import java.lang.annotation.Retention;
23 import java.lang.annotation.RetentionPolicy;
24 import java.util.Collection;
25 import java.util.Collections;
26 import java.util.Set;
27
28 /**
29 * When describing the features of the collection produced by a given generator (i.e. in a call to
30 * {@link
31 * com.google.common.collect.testing.FeatureSpecificTestSuiteBuilder#withFeatures(Feature...)}),
32 * this annotation specifies each of the different sizes for which a test suite should be built. (In
33 * a typical case, the features should include {@link CollectionSize#ANY}.) These semantics are thus
34 * a little different from those of other Collection-related features such as {@link
35 * CollectionFeature} or {@link SetFeature}.
36 *
37 * <p>However, when {@link CollectionSize.Require} is used to annotate a test it behaves normally
38 * (i.e. it requires the collection instance under test to be a certain size for the test to run).
39 * Note that this means a test should not require more than one CollectionSize, since a particular
40 * collection instance can only be one size at once.
41 *
42 * @author George van den Driessche
43 */
44 // Enum values use constructors with generic varargs.
45 @SuppressWarnings("unchecked")
46 @GwtCompatible
47 public enum CollectionSize implements Feature<Collection>, Comparable<CollectionSize> {
48 /** Test an empty collection. */
49 ZERO(0),
50 /** Test a one-element collection. */
51 ONE(1),
52 /** Test a three-element collection. */
53 SEVERAL(3),
54 /*
55 * TODO: add VERY_LARGE, noting that we currently assume that the fourth
56 * sample element is not in any collection
57 */
58
59 ANY(ZERO, ONE, SEVERAL);
60
61 private final Set<Feature<? super Collection>> implied;
62 private final Integer numElements;
63
64 CollectionSize(int numElements) {
65 this.implied = Collections.emptySet();
66 this.numElements = numElements;
67 }
68
69 CollectionSize(Feature<? super Collection>... implied) {
70 // Keep the order here, so that PerCollectionSizeTestSuiteBuilder
71 // gives a predictable order of test suites.
72 this.implied = Helpers.copyToSet(implied);
73 this.numElements = null;
74 }
75
76 @Override
77 public Set<Feature<? super Collection>> getImpliedFeatures() {
78 return implied;
79 }
80
81 public int getNumElements() {
82 if (numElements == null) {
83 throw new IllegalStateException(
84 "A compound CollectionSize doesn't specify a number of elements.");
85 }
86 return numElements;
87 }
88
89 @Retention(RetentionPolicy.RUNTIME)
90 @Inherited
91 @TesterAnnotation
92 public @interface Require {
93 CollectionSize[] value() default {};
94
95 CollectionSize[] absent() default {};
96 }
97 }