CollectionFeature.java revision 1d580d0f6ee4f21eb309ba7b509d2c6d671c4044 
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.collect.testing.Helpers;
20
21import java.lang.annotation.Inherited;
22import java.lang.annotation.Retention;
23import java.lang.annotation.RetentionPolicy;
24import java.util.Collection;
25import java.util.LinkedHashSet;
26import java.util.Set;
27import java.util.SortedSet;
28
29/**
30 * Optional features of classes derived from {@code Collection}.
31 *
32 * <p>This class is GWT compatible.
33 *
34 * @author George van den Driessche
35 */
36// Enum values use constructors with generic varargs.
37@SuppressWarnings("unchecked")
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 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_ADD_ALL,
86  SUPPORTS_REMOVE_ALL,
87  SUPPORTS_RETAIN_ALL,
88  SUPPORTS_CLEAR,
89
90  /**
91   * Features supported by general-purpose collections -
92   * everything but {@link #RESTRICTS_ELEMENTS}.
93   * @see java.util.Collection the definition of general-purpose collections.
94   */
95  GENERAL_PURPOSE(
96      SUPPORTS_ADD,
97      SUPPORTS_REMOVE,
98      SUPPORTS_ADD_ALL,
99      SUPPORTS_REMOVE_ALL,
100      SUPPORTS_RETAIN_ALL,
101      SUPPORTS_CLEAR),
102
103  /** Features supported by collections where only removal is allowed. */
104  REMOVE_OPERATIONS(
105      SUPPORTS_REMOVE,
106      SUPPORTS_REMOVE_ALL,
107      SUPPORTS_RETAIN_ALL,
108      SUPPORTS_CLEAR),
109
110  /**
111   * For documenting collections that support no optional features, such as
112   * {@link java.util.Collections#emptySet}
113   */
114  NONE();
115
116  private final Set<Feature<? super Collection>> implied;
117
118  CollectionFeature(Feature<? super Collection> ... implied) {
119    this.implied = Helpers.copyToSet(implied);
120  }
121
122  @Override
123  public Set<Feature<? super Collection>> getImpliedFeatures() {
124    return implied;
125  }
126
127  @Retention(RetentionPolicy.RUNTIME)
128  @Inherited
129  @TesterAnnotation
130  public @interface Require {
131    CollectionFeature[] value() default {};
132    CollectionFeature[] absent() default {};
133  }
134}
135