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.collect.testing.Helpers; 20 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 * <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") 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 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 CollectionFeature(Feature<? super Collection> .... implied)118 CollectionFeature(Feature<? super Collection> ... implied) { 119 this.implied = Helpers.copyToSet(implied); 120 } 121 122 @Override getImpliedFeatures()123 public Set<Feature<? super Collection>> getImpliedFeatures() { 124 return implied; 125 } 126 127 @Retention(RetentionPolicy.RUNTIME) 128 @Inherited 129 @TesterAnnotation 130 public @interface Require { value()131 CollectionFeature[] value() default {}; absent()132 CollectionFeature[] absent() default {}; 133 } 134 } 135