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