View Javadoc
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.GwtCompatible;
20  import com.google.errorprone.annotations.CanIgnoreReturnValue;
21  import java.util.Collection;
22  import java.util.Collections;
23  import java.util.Comparator;
24  import java.util.Map;
25  import java.util.SortedSet;
26  import javax.annotation.Nullable;
27  
28  /**
29   * Basic implementation of the {@link SortedSetMultimap} interface. It's a
30   * wrapper around {@link AbstractMapBasedMultimap} that converts the returned
31   * collections into sorted sets. The {@link #createCollection} method
32   * must return a {@code SortedSet}.
33   *
34   * @author Jared Levy
35   */
36  @GwtCompatible
37  abstract class AbstractSortedSetMultimap<K, V> extends AbstractSetMultimap<K, V>
38      implements SortedSetMultimap<K, V> {
39    /**
40     * Creates a new multimap that uses the provided map.
41     *
42     * @param map place to store the mapping from each key to its corresponding
43     *     values
44     */
45    protected AbstractSortedSetMultimap(Map<K, Collection<V>> map) {
46      super(map);
47    }
48  
49    @Override
50    abstract SortedSet<V> createCollection();
51  
52    @Override
53    SortedSet<V> createUnmodifiableEmptyCollection() {
54      Comparator<? super V> comparator = valueComparator();
55      if (comparator == null) {
56        return Collections.unmodifiableSortedSet(createCollection());
57      } else {
58        return ImmutableSortedSet.emptySet(valueComparator());
59      }
60    }
61  
62    // Following Javadoc copied from Multimap and SortedSetMultimap.
63  
64    /**
65     * Returns a collection view of all values associated with a key. If no
66     * mappings in the multimap have the provided key, an empty collection is
67     * returned.
68     *
69     * <p>Changes to the returned collection will update the underlying multimap,
70     * and vice versa.
71     *
72     * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given
73     * key, this method returns a {@link SortedSet}, instead of the
74     * {@link Collection} specified in the {@link Multimap} interface.
75     */
76    @Override
77    public SortedSet<V> get(@Nullable K key) {
78      return (SortedSet<V>) super.get(key);
79    }
80  
81    /**
82     * Removes all values associated with a given key. The returned collection is
83     * immutable.
84     *
85     * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given
86     * key, this method returns a {@link SortedSet}, instead of the
87     * {@link Collection} specified in the {@link Multimap} interface.
88     */
89    @CanIgnoreReturnValue
90    @Override
91    public SortedSet<V> removeAll(@Nullable Object key) {
92      return (SortedSet<V>) super.removeAll(key);
93    }
94  
95    /**
96     * Stores a collection of values with the same key, replacing any existing
97     * values for that key. The returned collection is immutable.
98     *
99     * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given
100    * key, this method returns a {@link SortedSet}, instead of the
101    * {@link Collection} specified in the {@link Multimap} interface.
102    *
103    * <p>Any duplicates in {@code values} will be stored in the multimap once.
104    */
105   @CanIgnoreReturnValue
106   @Override
107   public SortedSet<V> replaceValues(@Nullable K key, Iterable<? extends V> values) {
108     return (SortedSet<V>) super.replaceValues(key, values);
109   }
110 
111   /**
112    * Returns a map view that associates each key with the corresponding values
113    * in the multimap. Changes to the returned map, such as element removal, will
114    * update the underlying multimap. The map does not support {@code setValue}
115    * on its entries, {@code put}, or {@code putAll}.
116    *
117    * <p>When passed a key that is present in the map, {@code
118    * asMap().get(Object)} has the same behavior as {@link #get}, returning a
119    * live collection. When passed a key that is not present, however, {@code
120    * asMap().get(Object)} returns {@code null} instead of an empty collection.
121    *
122    * <p>Though the method signature doesn't say so explicitly, the returned map
123    * has {@link SortedSet} values.
124    */
125   @Override
126   public Map<K, Collection<V>> asMap() {
127     return super.asMap();
128   }
129 
130   /**
131    * {@inheritDoc}
132    *
133    * Consequently, the values do not follow their natural ordering or the
134    * ordering of the value comparator.
135    */
136   @Override
137   public Collection<V> values() {
138     return super.values();
139   }
140 
141   private static final long serialVersionUID = 430848587173315748L;
142 }