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