    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.GwtCompatible;
    020
    021    import java.util.Collection;
    022    import java.util.List;
    023    import java.util.Map;
    024
    025    import javax.annotation.Nullable;
    026
    027    /**
    028     * A {@code Multimap} that can hold duplicate key-value pairs and that maintains
    029     * the insertion ordering of values for a given key. See the {@link Multimap}
    030     * documentation for information common to all multimaps.
    031     *
    032     * <p>The {@link #get}, {@link #removeAll}, and {@link #replaceValues} methods
    033     * each return a {@link List} of values. Though the method signature doesn't say
    034     * so explicitly, the map returned by {@link #asMap} has {@code List} values.
    035     *
    036     * <p>See the Guava User Guide article on <a href=
    037     * "http://code.google.com/p/guava-libraries/wiki/NewCollectionTypesExplained#Multimap">
    038     * {@code Multimap}</a>.
    039     *
    040     * @author Jared Levy
    041     * @since 2.0 (imported from Google Collections Library)
    042     */
    043    @GwtCompatible
    044    public interface ListMultimap<K, V> extends Multimap<K, V> {
    045      /**
    046       * {@inheritDoc}
    047       *
    048       * <p>Because the values for a given key may have duplicates and follow the
    049       * insertion ordering, this method returns a {@link List}, instead of the
    050       * {@link java.util.Collection} specified in the {@link Multimap} interface.
    051       */
    052      @Override
    053      List<V> get(@Nullable K key);
    054
    055      /**
    056       * {@inheritDoc}
    057       *
    058       * <p>Because the values for a given key may have duplicates and follow the
    059       * insertion ordering, this method returns a {@link List}, instead of the
    060       * {@link java.util.Collection} specified in the {@link Multimap} interface.
    061       */
    062      @Override
    063      List<V> removeAll(@Nullable Object key);
    064
    065      /**
    066       * {@inheritDoc}
    067       *
    068       * <p>Because the values for a given key may have duplicates and follow the
    069       * insertion ordering, this method returns a {@link List}, instead of the
    070       * {@link java.util.Collection} specified in the {@link Multimap} interface.
    071       */
    072      @Override
    073      List<V> replaceValues(K key, Iterable<? extends V> values);
    074
    075      /**
    076       * {@inheritDoc}
    077       *
    078       * <p>Though the method signature doesn't say so explicitly, the returned map
    079       * has {@link List} values.
    080       */
    081      @Override
    082      Map<K, Collection<V>> asMap();
    083
    084      /**
    085       * Compares the specified object to this multimap for equality.
    086       *
    087       * <p>Two {@code ListMultimap} instances are equal if, for each key, they
    088       * contain the same values in the same order. If the value orderings disagree,
    089       * the multimaps will not be considered equal.
    090       *
    091       * <p>An empty {@code ListMultimap} is equal to any other empty {@code
    092       * Multimap}, including an empty {@code SetMultimap}.
    093       */
    094      @Override
    095      boolean equals(@Nullable Object obj);
    096    }