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.Map;
025import java.util.Set;
026
027/**
028 * Optional features of classes derived from {@code Map}.
029 *
030 * @author George van den Driessche
031 */
032@SuppressWarnings("rawtypes") // maybe avoidable if we rework the whole package?
033@GwtCompatible
034public enum MapFeature implements Feature<Map> {
035  /**
036   * The map does not throw {@code NullPointerException} on calls such as {@code containsKey(null)},
037   * {@code get(null)}, {@code keySet().contains(null)} or {@code remove(null)}.
038   */
039  ALLOWS_NULL_KEY_QUERIES,
040  ALLOWS_NULL_KEYS(ALLOWS_NULL_KEY_QUERIES),
041  /**
042   * The map does not throw {@code NullPointerException} on calls such as {@code
043   * containsValue(null)}, {@code values().contains(null)} or {@code values().remove(null)}.
044   */
045  ALLOWS_NULL_VALUE_QUERIES,
046  ALLOWS_NULL_VALUES(ALLOWS_NULL_VALUE_QUERIES),
047  /**
048   * The map does not throw {@code NullPointerException} on calls such as {@code
049   * entrySet().contains(null)} or {@code entrySet().remove(null)}
050   */
051  ALLOWS_NULL_ENTRY_QUERIES,
052  /**
053   * The map does not throw {@code NullPointerException} on any {@code null} queries.
054   *
055   * @see #ALLOWS_NULL_KEY_QUERIES
056   * @see #ALLOWS_NULL_VALUE_QUERIES
057   * @see #ALLOWS_NULL_ENTRY_QUERIES
058   */
059  ALLOWS_ANY_NULL_QUERIES(
060      ALLOWS_NULL_ENTRY_QUERIES, ALLOWS_NULL_KEY_QUERIES, ALLOWS_NULL_VALUE_QUERIES),
061  RESTRICTS_KEYS,
062  RESTRICTS_VALUES,
063  SUPPORTS_PUT,
064  SUPPORTS_REMOVE,
065  FAILS_FAST_ON_CONCURRENT_MODIFICATION,
066  /**
067   * Indicates that the constructor or factory method of a map, usually an immutable map, throws an
068   * {@link IllegalArgumentException} when presented with duplicate keys instead of discarding all
069   * but one.
070   */
071  REJECTS_DUPLICATES_AT_CREATION,
072
073  GENERAL_PURPOSE(SUPPORTS_PUT, SUPPORTS_REMOVE);
074
075  private final Set<Feature<? super Map>> implied;
076
077  MapFeature(Feature<? super Map>... implied) {
078    this.implied = Helpers.copyToSet(implied);
079  }
080
081  @Override
082  public Set<Feature<? super Map>> getImpliedFeatures() {
083    return implied;
084  }
085
086  @Retention(RetentionPolicy.RUNTIME)
087  @Inherited
088  @TesterAnnotation
089  public @interface Require {
090    public abstract MapFeature[] value() default {};
091
092    public abstract MapFeature[] absent() default {};
093  }
094}