CollectionFeature.java revision 7dd252788645e940eada959bdde927426e2531c9
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.annotations.GwtCompatible; 20import com.google.common.collect.testing.Helpers; 21 22import java.lang.annotation.Inherited; 23import java.lang.annotation.Retention; 24import java.lang.annotation.RetentionPolicy; 25import java.util.Collection; 26import java.util.LinkedHashSet; 27import java.util.Set; 28import java.util.SortedSet; 29 30/** 31 * Optional features of classes derived from {@code Collection}. 32 * 33 * <p>This class is GWT compatible. 34 * 35 * @author George van den Driessche 36 */ 37// Enum values use constructors with generic varargs. 38@SuppressWarnings("unchecked") 39@GwtCompatible 40public enum CollectionFeature implements Feature<Collection> { 41 /** 42 * The collection must not throw {@code NullPointerException} on calls 43 * such as {@code contains(null)} or {@code remove(null)}, but instead 44 * must return a simple {@code false}. 45 */ 46 ALLOWS_NULL_QUERIES, 47 48 ALLOWS_NULL_VALUES (ALLOWS_NULL_QUERIES), 49 50 /** 51 * Indicates that a collection disallows certain elements (other than 52 * {@code null}, whose validity as an element is indicated by the presence 53 * or absence of {@link #ALLOWS_NULL_VALUES}). 54 * From the documentation for {@link Collection}: 55 * <blockquote>"Some collection implementations have restrictions on the 56 * elements that they may contain. For example, some implementations 57 * prohibit null elements, and some have restrictions on the types of their 58 * elements."</blockquote> 59 */ 60 RESTRICTS_ELEMENTS, 61 62 /** 63 * Indicates that a collection has a well-defined ordering of its elements. 64 * The ordering may depend on the element values, such as a {@link SortedSet}, 65 * or on the insertion ordering, such as a {@link LinkedHashSet}. All list 66 * tests and sorted-collection tests automatically specify this feature. 67 */ 68 KNOWN_ORDER, 69 70 /** 71 * Indicates that a collection has a different {@link Object#toString} 72 * representation than most collections. If not specified, the collection 73 * tests will examine the value returned by {@link Object#toString}. 74 */ 75 NON_STANDARD_TOSTRING, 76 77 /** 78 * Indicates that the constructor or factory method of a collection, usually 79 * an immutable set, throws an {@link IllegalArgumentException} when presented 80 * with duplicate elements instead of collapsing them to a single element or 81 * including duplicate instances in the collection. 82 */ 83 REJECTS_DUPLICATES_AT_CREATION, 84 85 SUPPORTS_ADD, 86 SUPPORTS_REMOVE, 87 FAILS_FAST_ON_CONCURRENT_MODIFICATION, 88 89 /** 90 * Features supported by general-purpose collections - 91 * everything but {@link #RESTRICTS_ELEMENTS}. 92 * @see java.util.Collection the definition of general-purpose collections. 93 */ 94 GENERAL_PURPOSE( 95 SUPPORTS_ADD, 96 SUPPORTS_REMOVE), 97 98 /** Features supported by collections where only removal is allowed. */ 99 REMOVE_OPERATIONS( 100 SUPPORTS_REMOVE), 101 102 SERIALIZABLE, SERIALIZABLE_INCLUDING_VIEWS(SERIALIZABLE), 103 104 /** 105 * For documenting collections that support no optional features, such as 106 * {@link java.util.Collections#emptySet} 107 */ 108 NONE(); 109 110 private final Set<Feature<? super Collection>> implied; 111 112 CollectionFeature(Feature<? super Collection> ... implied) { 113 this.implied = Helpers.copyToSet(implied); 114 } 115 116 @Override 117 public Set<Feature<? super Collection>> getImpliedFeatures() { 118 return implied; 119 } 120 121 @Retention(RetentionPolicy.RUNTIME) 122 @Inherited 123 @TesterAnnotation 124 public @interface Require { 125 CollectionFeature[] value() default {}; 126 CollectionFeature[] absent() default {}; 127 } 128} 129