1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.collections4; 18 19 import java.util.Set; 20 21 /** 22 * Defines a map that allows bidirectional lookup between key and values. 23 * <p> 24 * This extended {@code Map} represents a mapping where a key may 25 * lookup a value and a value may lookup a key with equal ease. 26 * This interface extends {@code Map} and so may be used anywhere a map 27 * is required. The interface provides an inverse map view, enabling 28 * full access to both directions of the {@code BidiMap}. 29 * </p> 30 * <p> 31 * Implementations should allow a value to be looked up from a key and 32 * a key to be looked up from a value with equal performance. 33 * </p> 34 * <p> 35 * This map enforces the restriction that there is a 1:1 relation between 36 * keys and values, meaning that multiple keys cannot map to the same value. 37 * This is required so that "inverting" the map results in a map without 38 * duplicate keys. See the {@link #put} method description for more information. 39 * </p> 40 * 41 * @param <K> the type of the keys in the map 42 * @param <V> the type of the values in the map 43 * 44 * @since 3.0 45 */ 46 public interface BidiMap<K, V> extends IterableMap<K, V> { 47 48 /** 49 * Gets the key that is currently mapped to the specified value. 50 * <p> 51 * If the value is not contained in the map, {@code null} is returned. 52 * </p> 53 * <p> 54 * Implementations should seek to make this method perform equally as well 55 * as {@code get(Object)}. 56 * </p> 57 * 58 * @param value the value to find the key for 59 * @return the mapped key, or {@code null} if not found 60 * 61 * @throws ClassCastException (optional) if the map limits the type of the 62 * value and the specified value is inappropriate 63 * @throws NullPointerException (optional) if the map limits the values to 64 * non-null and null was specified 65 */ 66 K getKey(Object value); 67 68 /** 69 * Gets a view of this map where the keys and values are reversed. 70 * <p> 71 * Changes to one map will be visible in the other and vice versa. 72 * This enables both directions of the map to be accessed as a {@code Map}. 73 * </p> 74 * <p> 75 * Implementations should seek to avoid creating a new object every time this 76 * method is called. See {@code AbstractMap.values()} etc. Calling this 77 * method on the inverse map should return the original. 78 * </p> 79 * 80 * @return an inverted bidirectional map 81 */ 82 BidiMap<V, K> inverseBidiMap(); 83 84 /** 85 * Puts the key-value pair into the map, replacing any previous pair. 86 * <p> 87 * When adding a key-value pair, the value may already exist in the map 88 * against a different key. That mapping is removed, to ensure that the 89 * value only occurs once in the inverse map. 90 * </p> 91 * <pre> 92 * BidiMap map1 = new DualHashBidiMap(); 93 * map.put("A","B"); // contains A mapped to B, as per Map 94 * map.put("A","C"); // contains A mapped to C, as per Map 95 * 96 * BidiMap map2 = new DualHashBidiMap(); 97 * map.put("A","B"); // contains A mapped to B, as per Map 98 * map.put("C","B"); // contains C mapped to B, key A is removed 99 * </pre> 100 * 101 * @param key the key to store 102 * @param value the value to store 103 * @return the previous value mapped to this key 104 * 105 * @throws UnsupportedOperationException if the {@code put} method is not supported 106 * @throws ClassCastException (optional) if the map limits the type of the 107 * value and the specified value is inappropriate 108 * @throws IllegalArgumentException (optional) if the map limits the values 109 * in some way and the value was invalid 110 * @throws NullPointerException (optional) if the map limits the values to 111 * non-null and null was specified 112 */ 113 @Override 114 V put(K key, V value); 115 116 /** 117 * Removes the key-value pair that is currently mapped to the specified 118 * value (optional operation). 119 * <p> 120 * If the value is not contained in the map, {@code null} is returned. 121 * </p> 122 * <p> 123 * Implementations should seek to make this method perform equally as well 124 * as {@code remove(Object)}. 125 * </p> 126 * 127 * @param value the value to find the key-value pair for 128 * @return the key that was removed, {@code null} if nothing removed 129 * 130 * @throws ClassCastException (optional) if the map limits the type of the 131 * value and the specified value is inappropriate 132 * @throws NullPointerException (optional) if the map limits the values to 133 * non-null and null was specified 134 * @throws UnsupportedOperationException if this method is not supported 135 * by the implementation 136 */ 137 K removeValue(Object value); 138 139 /** 140 * Returns a {@link Set} view of the values contained in this map. 141 * The set is backed by the map, so changes to the map are reflected 142 * in the set, and vice-versa. If the map is modified while an iteration 143 * over the set is in progress (except through the iterator's own 144 * {@code remove} operation), the results of the iteration are undefined. 145 * The set supports element removal, which removes the corresponding 146 * mapping from the map, via the {@code Iterator.remove}, 147 * {@code Collection.remove}, {@code removeAll}, 148 * {@code retainAll} and {@code clear} operations. It does not 149 * support the {@code add} or {@code addAll} operations. 150 * 151 * @return a set view of the values contained in this map 152 */ 153 @Override 154 Set<V> values(); 155 }