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 import java.lang.annotation.Inherited;
22 import java.lang.annotation.Retention;
23 import java.lang.annotation.RetentionPolicy;
24 import java.util.Map;
25 import java.util.Set;
26 
27 /**
28  * Optional features of classes derived from {@code Map}.
29  *
30  * @author George van den Driessche
31  */
32 // Enum values use constructors with generic varargs.
33 @SuppressWarnings("unchecked")
34 @GwtCompatible
35 public enum MapFeature implements Feature<Map> {
36   /**
37    * The map does not throw {@code NullPointerException} on calls such as {@code containsKey(null)},
38    * {@code get(null)}, {@code keySet().contains(null)} or {@code remove(null)}.
39    */
40   ALLOWS_NULL_KEY_QUERIES,
41   ALLOWS_NULL_KEYS(ALLOWS_NULL_KEY_QUERIES),
42   /**
43    * The map does not throw {@code NullPointerException} on calls such as {@code
44    * containsValue(null)}, {@code values().contains(null)} or {@code values().remove(null)}.
45    */
46   ALLOWS_NULL_VALUE_QUERIES,
47   ALLOWS_NULL_VALUES(ALLOWS_NULL_VALUE_QUERIES),
48   /**
49    * The map does not throw {@code NullPointerException} on calls such as {@code
50    * entrySet().contains(null)} or {@code entrySet().remove(null)}
51    */
52   ALLOWS_NULL_ENTRY_QUERIES,
53   /**
54    * The map does not throw {@code NullPointerException} on any {@code null} queries.
55    *
56    * @see #ALLOWS_NULL_KEY_QUERIES
57    * @see #ALLOWS_NULL_VALUE_QUERIES
58    * @see #ALLOWS_NULL_ENTRY_QUERIES
59    */
60   ALLOWS_ANY_NULL_QUERIES(
61       ALLOWS_NULL_ENTRY_QUERIES, ALLOWS_NULL_KEY_QUERIES, ALLOWS_NULL_VALUE_QUERIES),
62   RESTRICTS_KEYS,
63   RESTRICTS_VALUES,
64   SUPPORTS_PUT,
65   SUPPORTS_REMOVE,
66   FAILS_FAST_ON_CONCURRENT_MODIFICATION,
67   /**
68    * Indicates that the constructor or factory method of a map, usually an immutable map, throws an
69    * {@link IllegalArgumentException} when presented with duplicate keys instead of discarding all
70    * but one.
71    */
72   REJECTS_DUPLICATES_AT_CREATION,
73 
74   GENERAL_PURPOSE(SUPPORTS_PUT, SUPPORTS_REMOVE);
75 
76   private final Set<Feature<? super Map>> implied;
77 
MapFeature(Feature<? super Map>.... implied)78   MapFeature(Feature<? super Map>... implied) {
79     this.implied = Helpers.copyToSet(implied);
80   }
81 
82   @Override
getImpliedFeatures()83   public Set<Feature<? super Map>> getImpliedFeatures() {
84     return implied;
85   }
86 
87   @Retention(RetentionPolicy.RUNTIME)
88   @Inherited
89   @TesterAnnotation
90   public @interface Require {
value()91     public abstract MapFeature[] value() default {};
92 
absent()93     public abstract MapFeature[] absent() default {};
94   }
95 }
96