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.Map; 022import java.util.Set; 023import javax.annotation.CheckForNull; 024import org.checkerframework.checker.nullness.qual.Nullable; 025 026/** 027 * A bimap (or "bidirectional map") is a map that preserves the uniqueness of its values as well as 028 * that of its keys. This constraint enables bimaps to support an "inverse view", which is another 029 * bimap containing the same entries as this bimap but with reversed keys and values. 030 * 031 * <h3>Implementations</h3> 032 * 033 * <ul> 034 * <li>{@link ImmutableBiMap} 035 * <li>{@link HashBiMap} 036 * <li>{@link EnumBiMap} 037 * <li>{@link EnumHashBiMap} 038 * </ul> 039 * 040 * <p>See the Guava User Guide article on <a href= 041 * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#bimap">{@code BiMap}</a>. 042 * 043 * @author Kevin Bourrillion 044 * @since 2.0 045 */ 046@GwtCompatible 047@ElementTypesAreNonnullByDefault 048public interface BiMap<K extends @Nullable Object, V extends @Nullable Object> extends Map<K, V> { 049 // Modification Operations 050 051 /** 052 * {@inheritDoc} 053 * 054 * @throws IllegalArgumentException if the given value is already bound to a different key in this 055 * bimap. The bimap will remain unmodified in this event. To avoid this exception, call {@link 056 * #forcePut} instead. 057 */ 058 @CanIgnoreReturnValue 059 @Override 060 @CheckForNull 061 V put(@ParametricNullness K key, @ParametricNullness V value); 062 063 /** 064 * An alternate form of {@code put} that silently removes any existing entry with the value {@code 065 * value} before proceeding with the {@link #put} operation. If the bimap previously contained the 066 * provided key-value mapping, this method has no effect. 067 * 068 * <p>Note that a successful call to this method could cause the size of the bimap to increase by 069 * one, stay the same, or even decrease by one. 070 * 071 * <p><b>Warning:</b> If an existing entry with this value is removed, the key for that entry is 072 * discarded and not returned. 073 * 074 * @param key the key with which the specified value is to be associated 075 * @param value the value to be associated with the specified key 076 * @return the value that was previously associated with the key, or {@code null} if there was no 077 * previous entry. (If the bimap contains null values, then {@code forcePut}, like {@code 078 * put}, returns {@code null} both if the key is absent and if it is present with a null 079 * value.) 080 */ 081 @CanIgnoreReturnValue 082 @CheckForNull 083 V forcePut(@ParametricNullness K key, @ParametricNullness V value); 084 085 // Bulk Operations 086 087 /** 088 * {@inheritDoc} 089 * 090 * <p><b>Warning:</b> the results of calling this method may vary depending on the iteration order 091 * of {@code map}. 092 * 093 * @throws IllegalArgumentException if an attempt to {@code put} any entry fails. Note that some 094 * map entries may have been added to the bimap before the exception was thrown. 095 */ 096 @Override 097 void putAll(Map<? extends K, ? extends V> map); 098 099 // Views 100 101 /** 102 * {@inheritDoc} 103 * 104 * <p>Because a bimap has unique values, this method returns a {@link Set}, instead of the {@link 105 * java.util.Collection} specified in the {@link Map} interface. 106 */ 107 @Override 108 Set<V> values(); 109 110 /** 111 * Returns the inverse view of this bimap, which maps each of this bimap's values to its 112 * associated key. The two bimaps are backed by the same data; any changes to one will appear in 113 * the other. 114 * 115 * <p><b>Note:</b>There is no guaranteed correspondence between the iteration order of a bimap and 116 * that of its inverse. 117 * 118 * @return the inverse view of this bimap 119 */ 120 BiMap<V, K> inverse(); 121}