Java

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
@SuppressWarnings("rawtypes") // maybe avoidable if we rework the whole package?
35
@GwtCompatible
36
public enum CollectionFeature implements Feature<Collection> {
37
  /**
38
   * The collection must not throw {@code NullPointerException} on calls such as {@code
39
   * contains(null)} or {@code remove(null)}, but instead must return a simple {@code false}.
40
   */
41
  ALLOWS_NULL_QUERIES,
42
  ALLOWS_NULL_VALUES(ALLOWS_NULL_QUERIES),
43

44
  /**
45
   * Indicates that a collection disallows certain elements (other than {@code null}, whose validity
46
   * as an element is indicated by the presence or absence of {@link #ALLOWS_NULL_VALUES}). From the
47
   * documentation for {@link Collection}:
48
   *
49
   * <blockquote>
50
   *
51
   * "Some collection implementations have restrictions on the elements that they may contain. For
52
   * example, some implementations prohibit null elements, and some have restrictions on the types
53
   * of their elements."
54
   *
55
   * </blockquote>
56
   */
57
  RESTRICTS_ELEMENTS,
58

59
  /**
60
   * Indicates that a collection has a well-defined ordering of its elements. The ordering may
61
   * depend on the element values, such as a {@link SortedSet}, or on the insertion ordering, such
62
   * as a {@link LinkedHashSet}. All list tests and sorted-collection tests automatically specify
63
   * this feature.
64
   */
65
  KNOWN_ORDER,
66

67
  /**
68
   * Indicates that a collection has a different {@link Object#toString} representation than most
69
   * collections. If not specified, the collection tests will examine the value returned by {@link
70
   * Object#toString}.
71
   */
72
  NON_STANDARD_TOSTRING,
73

74
  /**
75
   * Indicates that the constructor or factory method of a collection, usually an immutable set,
76
   * throws an {@link IllegalArgumentException} when presented with duplicate elements instead of
77
   * collapsing them to a single element or 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 - everything but {@link #RESTRICTS_ELEMENTS}.
88
   *
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 {@link
104
   * 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
}
128