001/*
002 * Copyright (C) 2008 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.google.common.collect.testing.features;
018
019import com.google.common.annotations.GwtCompatible;
020import com.google.common.collect.testing.Helpers;
021import java.lang.annotation.Inherited;
022import java.lang.annotation.Retention;
023import java.lang.annotation.RetentionPolicy;
024import java.util.Collection;
025import java.util.LinkedHashSet;
026import java.util.Set;
027import java.util.SortedSet;
028
029/**
030 * Optional features of classes derived from {@code Collection}.
031 *
032 * @author George van den Driessche
033 */
034@SuppressWarnings("rawtypes") // maybe avoidable if we rework the whole package?
035@GwtCompatible
036public enum CollectionFeature implements Feature<Collection> {
037  /**
038   * The collection must not throw {@code NullPointerException} on calls such as {@code
039   * contains(null)} or {@code remove(null)}, but instead must return a simple {@code false}.
040   */
041  ALLOWS_NULL_QUERIES,
042  ALLOWS_NULL_VALUES(ALLOWS_NULL_QUERIES),
043
044  /**
045   * Indicates that a collection disallows certain elements (other than {@code null}, whose validity
046   * as an element is indicated by the presence or absence of {@link #ALLOWS_NULL_VALUES}). From the
047   * documentation for {@link Collection}:
048   *
049   * <blockquote>
050   *
051   * "Some collection implementations have restrictions on the elements that they may contain. For
052   * example, some implementations prohibit null elements, and some have restrictions on the types
053   * of their elements."
054   *
055   * </blockquote>
056   */
057  RESTRICTS_ELEMENTS,
058
059  /**
060   * Indicates that a collection has a well-defined ordering of its elements. The ordering may
061   * depend on the element values, such as a {@link SortedSet}, or on the insertion ordering, such
062   * as a {@link LinkedHashSet}. All list tests and sorted-collection tests automatically specify
063   * this feature.
064   */
065  KNOWN_ORDER,
066
067  /**
068   * Indicates that a collection has a different {@link Object#toString} representation than most
069   * collections. If not specified, the collection tests will examine the value returned by {@link
070   * Object#toString}.
071   */
072  NON_STANDARD_TOSTRING,
073
074  /**
075   * Indicates that the constructor or factory method of a collection, usually an immutable set,
076   * throws an {@link IllegalArgumentException} when presented with duplicate elements instead of
077   * collapsing them to a single element or including duplicate instances in the collection.
078   */
079  REJECTS_DUPLICATES_AT_CREATION,
080
081  SUPPORTS_ADD,
082  SUPPORTS_REMOVE,
083  SUPPORTS_ITERATOR_REMOVE,
084  FAILS_FAST_ON_CONCURRENT_MODIFICATION,
085
086  /**
087   * Features supported by general-purpose collections - everything but {@link #RESTRICTS_ELEMENTS}.
088   *
089   * @see java.util.Collection the definition of general-purpose collections.
090   */
091  GENERAL_PURPOSE(SUPPORTS_ADD, SUPPORTS_REMOVE, SUPPORTS_ITERATOR_REMOVE),
092
093  /** Features supported by collections where only removal is allowed. */
094  REMOVE_OPERATIONS(SUPPORTS_REMOVE, SUPPORTS_ITERATOR_REMOVE),
095
096  SERIALIZABLE,
097  SERIALIZABLE_INCLUDING_VIEWS(SERIALIZABLE),
098
099  SUBSET_VIEW,
100  DESCENDING_VIEW,
101
102  /**
103   * For documenting collections that support no optional features, such as {@link
104   * java.util.Collections#emptySet}
105   */
106  NONE;
107
108  private final Set<Feature<? super Collection>> implied;
109
110  CollectionFeature(Feature<? super Collection>... implied) {
111    this.implied = Helpers.copyToSet(implied);
112  }
113
114  @Override
115  public Set<Feature<? super Collection>> getImpliedFeatures() {
116    return implied;
117  }
118
119  @Retention(RetentionPolicy.RUNTIME)
120  @Inherited
121  @TesterAnnotation
122  public @interface Require {
123    CollectionFeature[] value() default {};
124
125    CollectionFeature[] absent() default {};
126  }
127}