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