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.Map; 22090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport java.util.Set; 23090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 24090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonimport javax.annotation.Nullable; 25090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 26090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson/** 27090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * A bimap (or "bidirectional map") is a map that preserves the uniqueness of 28090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * its values as well as that of its keys. This constraint enables bimaps to 29090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * support an "inverse view", which is another bimap containing the same entries 30090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * as this bimap but with reversed keys and values. 31090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 32090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @author Kevin Bourrillion 331d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 2.0 (imported from Google Collections Library) 34090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 35090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson@GwtCompatible 36090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilsonpublic interface BiMap<K, V> extends Map<K, V> { 37090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson // Modification Operations 38090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 39090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 40090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@inheritDoc} 41090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 42090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @throws IllegalArgumentException if the given value is already bound to a 43090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * different key in this bimap. The bimap will remain unmodified in this 44090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * event. To avoid this exception, call {@link #forcePut} instead. 45090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 461d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert @Override 47090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson V put(@Nullable K key, @Nullable V value); 48090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 49090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 50090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * An alternate form of {@code put} that silently removes any existing entry 51090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * with the value {@code value} before proceeding with the {@link #put} 52090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * operation. If the bimap previously contained the provided key-value 53090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * mapping, this method has no effect. 54090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 55090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>Note that a successful call to this method could cause the size of the 56090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * bimap to increase by one, stay the same, or even decrease by one. 57090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 581d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * <p><b>Warning:</b> If an existing entry with this value is removed, the key 59090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * for that entry is discarded and not returned. 60090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 61090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param key the key with which the specified value is to be associated 62090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @param value the value to be associated with the specified key 63090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @return the value which was previously associated with the key, which may 64090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * be {@code null}, or {@code null} if there was no previous entry 65090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 66090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson V forcePut(@Nullable K key, @Nullable V value); 67090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 68090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson // Bulk Operations 69090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 70090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 71090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@inheritDoc} 72090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 73090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p><b>Warning:</b> the results of calling this method may vary depending on 74090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * the iteration order of {@code map}. 75090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 76090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @throws IllegalArgumentException if an attempt to {@code put} any 77090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * entry fails. Note that some map entries may have been added to the 78090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * bimap before the exception was thrown. 79090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 801d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert @Override 81090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson void putAll(Map<? extends K, ? extends V> map); 82090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 83090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson // Views 84090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 85090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 86090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * {@inheritDoc} 87090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 88090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p>Because a bimap has unique values, this method returns a {@link Set}, 89090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * instead of the {@link java.util.Collection} specified in the {@link Map} 90090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * interface. 91090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 921d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert @Override 93090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson Set<V> values(); 94090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson 95090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson /** 96090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * Returns the inverse view of this bimap, which maps each of this bimap's 97090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * values to its associated key. The two bimaps are backed by the same data; 98090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * any changes to one will appear in the other. 99090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 100090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * <p><b>Note:</b>There is no guaranteed correspondence between the iteration 101090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * order of a bimap and that of its inverse. 102090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * 103090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson * @return the inverse view of this bimap 104090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson */ 105090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson BiMap<V, K> inverse(); 106090f9b4c879985bc747c214f82c62471e60c7742Jesse Wilson} 107