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