1090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson/*
21d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Copyright (C) 2007 The Guava Authors
3090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson *
4090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Licensed under the Apache License, Version 2.0 (the "License");
5090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * you may not use this file except in compliance with the License.
6090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * You may obtain a copy of the License at
7090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson *
8090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * http://www.apache.org/licenses/LICENSE-2.0
9090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson *
10090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Unless required by applicable law or agreed to in writing, software
11090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * distributed under the License is distributed on an "AS IS" BASIS,
12090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * See the License for the specific language governing permissions and
14090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * limitations under the License.
15090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */
16090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson
17090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonpackage com.google.common.collect;
18090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson
19090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport com.google.common.annotations.GwtCompatible;
20090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson
21090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.Collection;
22090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.Comparator;
23090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.Map;
24090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.Set;
25090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.SortedSet;
26090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson
27090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport javax.annotation.Nullable;
28090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson
29090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson/**
30090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * A {@code SetMultimap} whose set of values for a given key are kept sorted;
31090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * that is, they comprise a {@link SortedSet}. It cannot hold duplicate
32090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * key-value pairs; adding a key-value pair that's already in the multimap has
33090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * no effect. This interface does not specify the ordering of the multimap's
34090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * keys.
35090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson *
36090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>The {@link #get}, {@link #removeAll}, and {@link #replaceValues} methods
37090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * each return a {@link SortedSet} of values, while {@link Multimap#entries()}
38090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * returns a {@link Set} of map entries. Though the method signature doesn't say
39090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * so explicitly, the map returned by {@link #asMap} has {@code SortedSet}
40090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * values.
41090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson *
42090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @author Jared Levy
431d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 2.0 (imported from Google Collections Library)
44090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */
45090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson@GwtCompatible
46090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonpublic interface SortedSetMultimap<K, V> extends SetMultimap<K, V> {
471d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert  // Following Javadoc copied from Multimap.
481d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert
49090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson  /**
50090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * Returns a collection view of all values associated with a key. If no
51090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * mappings in the multimap have the provided key, an empty collection is
52090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * returned.
53090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   *
54090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * <p>Changes to the returned collection will update the underlying multimap,
55090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * and vice versa.
56090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   *
57090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given
58090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * key, this method returns a {@link SortedSet}, instead of the
59090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * {@link java.util.Collection} specified in the {@link Multimap} interface.
60090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   */
611d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert  @Override
62090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson  SortedSet<V> get(@Nullable K key);
63090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson
64090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson  /**
65090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * Removes all values associated with a given key.
66090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   *
67090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given
68090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * key, this method returns a {@link SortedSet}, instead of the
69090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * {@link java.util.Collection} specified in the {@link Multimap} interface.
70090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   */
711d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert  @Override
72090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson  SortedSet<V> removeAll(@Nullable Object key);
73090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson
74090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson  /**
75090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * Stores a collection of values with the same key, replacing any existing
76090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * values for that key.
77090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   *
78090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given
79090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * key, this method returns a {@link SortedSet}, instead of the
80090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * {@link java.util.Collection} specified in the {@link Multimap} interface.
81090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   *
82090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * <p>Any duplicates in {@code values} will be stored in the multimap once.
83090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   */
841d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert  @Override
85090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson  SortedSet<V> replaceValues(K key, Iterable<? extends V> values);
86090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson
87090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson  /**
88090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * Returns a map view that associates each key with the corresponding values
891d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   * in the multimap. Changes to the returned map, such as element removal, will
901d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   * update the underlying multimap. The map does not support {@code setValue()}
911d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   * on its entries, {@code put}, or {@code putAll}.
92090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   *
931d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   * <p>When passed a key that is present in the map, {@code
941d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   * asMap().get(Object)} has the same behavior as {@link #get}, returning a
951d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   * live collection. When passed a key that is not present, however, {@code
961d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   * asMap().get(Object)} returns {@code null} instead of an empty collection.
97090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   *
98090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * <p>Though the method signature doesn't say so explicitly, the returned map
99090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * has {@link SortedSet} values.
100090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   */
1011d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert  @Override
102090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson  Map<K, Collection<V>> asMap();
103090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson
104090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson  /**
1051d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   * Returns the comparator that orders the multimap values, with {@code null}
106090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   * indicating that natural ordering is used.
107090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson   */
108090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson  Comparator<? super V> valueComparator();
109090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson}
110