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