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 017package com.google.common.collect; 018 019import com.google.common.annotations.GwtCompatible; 020import com.google.errorprone.annotations.CanIgnoreReturnValue; 021import java.util.Collection; 022import java.util.Comparator; 023import java.util.Map; 024import java.util.Set; 025import java.util.SortedSet; 026import org.checkerframework.checker.nullness.qual.Nullable; 027 028/** 029 * A {@code SetMultimap} whose set of values for a given key are kept sorted; that is, they comprise 030 * a {@link SortedSet}. It cannot hold duplicate key-value pairs; adding a key-value pair that's 031 * already in the multimap has no effect. This interface does not specify the ordering of the 032 * multimap's keys. See the {@link Multimap} documentation for information common to all multimaps. 033 * 034 * <p>The {@link #get}, {@link #removeAll}, and {@link #replaceValues} methods each return a {@link 035 * SortedSet} of values, while {@link Multimap#entries()} returns a {@link Set} of map entries. 036 * Though the method signature doesn't say so explicitly, the map returned by {@link #asMap} has 037 * {@code SortedSet} values. 038 * 039 * <p>See the Guava User Guide article on <a href= 040 * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#multimap"> {@code 041 * Multimap}</a>. 042 * 043 * @author Jared Levy 044 * @since 2.0 045 */ 046@GwtCompatible 047public interface SortedSetMultimap<K, V> extends SetMultimap<K, V> { 048 // Following Javadoc copied from Multimap. 049 050 /** 051 * Returns a collection view of all values associated with a key. If no mappings in the multimap 052 * have the provided key, an empty collection is returned. 053 * 054 * <p>Changes to the returned collection will update the underlying multimap, and vice versa. 055 * 056 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given key, this method 057 * returns a {@link SortedSet}, instead of the {@link java.util.Collection} specified in the 058 * {@link Multimap} interface. 059 */ 060 @Override 061 SortedSet<V> get(@Nullable K key); 062 063 /** 064 * Removes all values associated with a given key. 065 * 066 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given key, this method 067 * returns a {@link SortedSet}, instead of the {@link java.util.Collection} specified in the 068 * {@link Multimap} interface. 069 */ 070 @CanIgnoreReturnValue 071 @Override 072 SortedSet<V> removeAll(@Nullable Object key); 073 074 /** 075 * Stores a collection of values with the same key, replacing any existing values for that key. 076 * 077 * <p>Because a {@code SortedSetMultimap} has unique sorted values for a given key, this method 078 * returns a {@link SortedSet}, instead of the {@link java.util.Collection} specified in the 079 * {@link Multimap} interface. 080 * 081 * <p>Any duplicates in {@code values} will be stored in the multimap once. 082 */ 083 @CanIgnoreReturnValue 084 @Override 085 SortedSet<V> replaceValues(K key, Iterable<? extends V> values); 086 087 /** 088 * Returns a map view that associates each key with the corresponding values in the multimap. 089 * Changes to the returned map, such as element removal, will update the underlying multimap. The 090 * map does not support {@code setValue()} on its entries, {@code put}, or {@code putAll}. 091 * 092 * <p>When passed a key that is present in the map, {@code asMap().get(Object)} has the same 093 * behavior as {@link #get}, returning a live collection. When passed a key that is not present, 094 * however, {@code asMap().get(Object)} returns {@code null} instead of an empty collection. 095 * 096 * <p><b>Note:</b> The returned map's values are guaranteed to be of type {@link SortedSet}. To 097 * obtain this map with the more specific generic type {@code Map<K, SortedSet<V>>}, call {@link 098 * Multimaps#asMap(SortedSetMultimap)} instead. 099 */ 100 @Override 101 Map<K, Collection<V>> asMap(); 102 103 /** 104 * Returns the comparator that orders the multimap values, with {@code null} indicating that 105 * natural ordering is used. 106 */ 107 Comparator<? super V> valueComparator(); 108}