1 /* 2 * Copyright (C) 2007 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; 18 19 import com.google.common.annotations.Beta; 20 import com.google.common.annotations.GwtCompatible; 21 22 import javax.annotation.Nullable; 23 24 /** 25 * A constraint on the keys and values that may be added to a {@code Map} or 26 * {@code Multimap}. For example, {@link MapConstraints#notNull()}, which 27 * prevents a map from including any null keys or values, could be implemented 28 * like this: <pre> {@code 29 * 30 * public void checkKeyValue(Object key, Object value) { 31 * if (key == null || value == null) { 32 * throw new NullPointerException(); 33 * } 34 * }}</pre> 35 * 36 * <p>In order to be effective, constraints should be deterministic; that is, they 37 * should not depend on state that can change (such as external state, random 38 * variables, and time) and should only depend on the value of the passed-in key 39 * and value. A non-deterministic constraint cannot reliably enforce that all 40 * the collection's elements meet the constraint, since the constraint is only 41 * enforced when elements are added. 42 * 43 * @author Mike Bostock 44 * @see MapConstraints 45 * @see Constraint 46 * @since 3.0 47 */ 48 @GwtCompatible 49 @Beta 50 public interface MapConstraint<K, V> { 51 /** 52 * Throws a suitable {@code RuntimeException} if the specified key or value is 53 * illegal. Typically this is either a {@link NullPointerException}, an 54 * {@link IllegalArgumentException}, or a {@link ClassCastException}, though 55 * an application-specific exception class may be used if appropriate. 56 */ checkKeyValue(@ullable K key, @Nullable V value)57 void checkKeyValue(@Nullable K key, @Nullable V value); 58 59 /** 60 * Returns a brief human readable description of this constraint, such as 61 * "Not null". 62 */ 63 @Override toString()64 String toString(); 65 } 66