    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.
    030     *
    031     * <p>The {@link #get}, {@link #removeAll}, and {@link #replaceValues} methods
    032     * each return a {@link List} of values. Though the method signature doesn't say
    033     * so explicitly, the map returned by {@link #asMap} has {@code List} values.
    034     *
    035     * @author Jared Levy
    036     * @since 2.0 (imported from Google Collections Library)
    037     */
    038    @GwtCompatible
    039    public interface ListMultimap<K, V> extends Multimap<K, V> {
    040      /**
    041       * {@inheritDoc}
    042       *
    043       * <p>Because the values for a given key may have duplicates and follow the
    044       * insertion ordering, this method returns a {@link List}, instead of the
    045       * {@link java.util.Collection} specified in the {@link Multimap} interface.
    046       */
    047      @Override
    048      List<V> get(@Nullable K key);
    049
    050      /**
    051       * {@inheritDoc}
    052       *
    053       * <p>Because the values for a given key may have duplicates and follow the
    054       * insertion ordering, this method returns a {@link List}, instead of the
    055       * {@link java.util.Collection} specified in the {@link Multimap} interface.
    056       */
    057      @Override
    058      List<V> removeAll(@Nullable Object key);
    059
    060      /**
    061       * {@inheritDoc}
    062       *
    063       * <p>Because the values for a given key may have duplicates and follow the
    064       * insertion ordering, this method returns a {@link List}, instead of the
    065       * {@link java.util.Collection} specified in the {@link Multimap} interface.
    066       */
    067      @Override
    068      List<V> replaceValues(K key, Iterable<? extends V> values);
    069
    070      /**
    071       * {@inheritDoc}
    072       *
    073       * <p>Though the method signature doesn't say so explicitly, the returned map
    074       * has {@link List} values.
    075       */
    076      @Override
    077      Map<K, Collection<V>> asMap();
    078
    079      /**
    080       * Compares the specified object to this multimap for equality.
    081       *
    082       * <p>Two {@code ListMultimap} instances are equal if, for each key, they
    083       * contain the same values in the same order. If the value orderings disagree,
    084       * the multimaps will not be considered equal.
    085       */
    086      @Override
    087      boolean equals(@Nullable Object obj);
    088    }