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