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