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 CollectionFeature(Feature<? super Collection>.... implied)111 CollectionFeature(Feature<? super Collection>... implied) { 112 this.implied = Helpers.copyToSet(implied); 113 } 114 115 @Override getImpliedFeatures()116 public Set<Feature<? super Collection>> getImpliedFeatures() { 117 return implied; 118 } 119 120 @Retention(RetentionPolicy.RUNTIME) 121 @Inherited 122 @TesterAnnotation 123 public @interface Require { value()124 CollectionFeature[] value() default {}; 125 absent()126 CollectionFeature[] absent() default {}; 127 } 128 } 129