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