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