CollectionFeature.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.LinkedHashSet;
27import java.util.Set;
28import java.util.SortedSet;
29
30/**
31 * Optional features of classes derived from {@code Collection}.
32 *
33 * <p>This class is GWT compatible.
34 *
35 * @author George van den Driessche
36 */
37// Enum values use constructors with generic varargs.
38@SuppressWarnings("unchecked")
39@GwtCompatible
40public enum CollectionFeature implements Feature<Collection> {
41  /**
42   * The collection must not throw {@code NullPointerException} on calls
43   * such as {@code contains(null)} or {@code remove(null)}, but instead
44   * must return a simple {@code false}.
45   */
46  ALLOWS_NULL_QUERIES,
47
48  ALLOWS_NULL_VALUES (ALLOWS_NULL_QUERIES),
49
50  /**
51   * Indicates that a collection disallows certain elements (other than
52   * {@code null}, whose validity as an element is indicated by the presence
53   * or absence of {@link #ALLOWS_NULL_VALUES}).
54   * From the documentation for {@link Collection}:
55   * <blockquote>"Some collection implementations have restrictions on the
56   * elements that they may contain.  For example, some implementations
57   * prohibit null elements, and some have restrictions on the types of their
58   * elements."</blockquote>
59   */
60  RESTRICTS_ELEMENTS,
61
62  /**
63   * Indicates that a collection has a well-defined ordering of its elements.
64   * The ordering may depend on the element values, such as a {@link SortedSet},
65   * or on the insertion ordering, such as a {@link LinkedHashSet}. All list
66   * tests and sorted-collection tests automatically specify this feature.
67   */
68  KNOWN_ORDER,
69
70  /**
71   * Indicates that a collection has a different {@link Object#toString}
72   * representation than most collections. If not specified, the collection
73   * tests will examine the value returned by {@link Object#toString}.
74   */
75  NON_STANDARD_TOSTRING,
76
77  /**
78   * Indicates that the constructor or factory method of a collection, usually
79   * an immutable set, throws an {@link IllegalArgumentException} when presented
80   * with duplicate elements instead of collapsing them to a single element or
81   * including duplicate instances in the collection.
82   */
83  REJECTS_DUPLICATES_AT_CREATION,
84
85  SUPPORTS_ADD,
86  SUPPORTS_REMOVE,
87  FAILS_FAST_ON_CONCURRENT_MODIFICATION,
88
89  /**
90   * Features supported by general-purpose collections -
91   * everything but {@link #RESTRICTS_ELEMENTS}.
92   * @see java.util.Collection the definition of general-purpose collections.
93   */
94  GENERAL_PURPOSE(
95      SUPPORTS_ADD,
96      SUPPORTS_REMOVE),
97
98  /** Features supported by collections where only removal is allowed. */
99  REMOVE_OPERATIONS(
100      SUPPORTS_REMOVE),
101
102  SERIALIZABLE, SERIALIZABLE_INCLUDING_VIEWS(SERIALIZABLE),
103
104  /**
105   * For documenting collections that support no optional features, such as
106   * {@link java.util.Collections#emptySet}
107   */
108  NONE();
109
110  private final Set<Feature<? super Collection>> implied;
111
112  CollectionFeature(Feature<? super Collection> ... implied) {
113    this.implied = Helpers.copyToSet(implied);
114  }
115
116  @Override
117  public Set<Feature<? super Collection>> getImpliedFeatures() {
118    return implied;
119  }
120
121  @Retention(RetentionPolicy.RUNTIME)
122  @Inherited
123  @TesterAnnotation
124  public @interface Require {
125    CollectionFeature[] value() default {};
126    CollectionFeature[] absent() default {};
127  }
128}
129