Home | History | Annotate | Download | only in features 
      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 
    116   CollectionFeature(Feature<? super Collection> ... implied) {
    117     this.implied = Helpers.copyToSet(implied);
    118   }
    119 
    120   @Override
    121   public Set<Feature<? super Collection>> getImpliedFeatures() {
    122     return implied;
    123   }
    124 
    125   @Retention(RetentionPolicy.RUNTIME)
    126   @Inherited
    127   @TesterAnnotation
    128   public @interface Require {
    129     CollectionFeature[] value() default {};
    130     CollectionFeature[] absent() default {};
    131   }
    132 }
    133