    001    /*
    002     * Copyright (C) 2007 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
    017    package com.google.common.collect;
    018
    019    import com.google.common.annotations.Beta;
    020    import com.google.common.annotations.GwtCompatible;
    021
    022    import javax.annotation.Nullable;
    023
    024    /**
    025     * A constraint on the keys and values that may be added to a {@code Map} or
    026     * {@code Multimap}. For example, {@link MapConstraints#notNull()}, which
    027     * prevents a map from including any null keys or values, could be implemented
    028     * like this: <pre>   {@code
    029     *
    030     *   public void checkKeyValue(Object key, Object value) {
    031     *     if (key == null || value == null) {
    032     *       throw new NullPointerException();
    033     *     }
    034     *   }}</pre>
    035     *
    036     * In order to be effective, constraints should be deterministic; that is, they
    037     * should not depend on state that can change (such as external state, random
    038     * variables, and time) and should only depend on the value of the passed-in key
    039     * and value. A non-deterministic constraint cannot reliably enforce that all
    040     * the collection's elements meet the constraint, since the constraint is only
    041     * enforced when elements are added.
    042     *
    043     * @author Mike Bostock
    044     * @see MapConstraints
    045     * @see Constraint
    046     * @since 3.0
    047     */
    048    @GwtCompatible
    049    @Beta
    050    public interface MapConstraint<K, V> {
    051      /**
    052       * Throws a suitable {@code RuntimeException} if the specified key or value is
    053       * illegal. Typically this is either a {@link NullPointerException}, an
    054       * {@link IllegalArgumentException}, or a {@link ClassCastException}, though
    055       * an application-specific exception class may be used if appropriate.
    056       */
    057      void checkKeyValue(@Nullable K key, @Nullable V value);
    058
    059      /**
    060       * Returns a brief human readable description of this constraint, such as
    061       * "Not null".
    062       */
    063      @Override
    064      String toString();
    065    }