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 
22 import java.lang.annotation.Inherited;
23 import java.lang.annotation.Retention;
24 import java.lang.annotation.RetentionPolicy;
25 import java.util.Collection;
26 import java.util.LinkedHashSet;
27 import java.util.Set;
28 import 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
38 public 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 
CollectionFeature(Feature<? super Collection> .... implied)116   CollectionFeature(Feature<? super Collection> ... implied) {
117     this.implied = Helpers.copyToSet(implied);
118   }
119 
120   @Override
getImpliedFeatures()121   public Set<Feature<? super Collection>> getImpliedFeatures() {
122     return implied;
123   }
124 
125   @Retention(RetentionPolicy.RUNTIME)
126   @Inherited
127   @TesterAnnotation
128   public @interface Require {
value()129     CollectionFeature[] value() default {};
absent()130     CollectionFeature[] absent() default {};
131   }
132 }
133