001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.collections4; 018 019import java.util.Set; 020 021/** 022 * Defines a map that allows bidirectional lookup between key and values. 023 * <p> 024 * This extended {@code Map} represents a mapping where a key may 025 * lookup a value and a value may lookup a key with equal ease. 026 * This interface extends {@code Map} and so may be used anywhere a map 027 * is required. The interface provides an inverse map view, enabling 028 * full access to both directions of the {@code BidiMap}. 029 * </p> 030 * <p> 031 * Implementations should allow a value to be looked up from a key and 032 * a key to be looked up from a value with equal performance. 033 * </p> 034 * <p> 035 * This map enforces the restriction that there is a 1:1 relation between 036 * keys and values, meaning that multiple keys cannot map to the same value. 037 * This is required so that "inverting" the map results in a map without 038 * duplicate keys. See the {@link #put} method description for more information. 039 * </p> 040 * 041 * @param <K> the type of the keys in the map 042 * @param <V> the type of the values in the map 043 * 044 * @since 3.0 045 */ 046public interface BidiMap<K, V> extends IterableMap<K, V> { 047 048 /** 049 * Gets the key that is currently mapped to the specified value. 050 * <p> 051 * If the value is not contained in the map, {@code null} is returned. 052 * </p> 053 * <p> 054 * Implementations should seek to make this method perform equally as well 055 * as {@code get(Object)}. 056 * </p> 057 * 058 * @param value the value to find the key for 059 * @return the mapped key, or {@code null} if not found 060 * 061 * @throws ClassCastException (optional) if the map limits the type of the 062 * value and the specified value is inappropriate 063 * @throws NullPointerException (optional) if the map limits the values to 064 * non-null and null was specified 065 */ 066 K getKey(Object value); 067 068 /** 069 * Gets a view of this map where the keys and values are reversed. 070 * <p> 071 * Changes to one map will be visible in the other and vice versa. 072 * This enables both directions of the map to be accessed as a {@code Map}. 073 * </p> 074 * <p> 075 * Implementations should seek to avoid creating a new object every time this 076 * method is called. See {@code AbstractMap.values()} etc. Calling this 077 * method on the inverse map should return the original. 078 * </p> 079 * 080 * @return an inverted bidirectional map 081 */ 082 BidiMap<V, K> inverseBidiMap(); 083 084 /** 085 * Puts the key-value pair into the map, replacing any previous pair. 086 * <p> 087 * When adding a key-value pair, the value may already exist in the map 088 * against a different key. That mapping is removed, to ensure that the 089 * value only occurs once in the inverse map. 090 * </p> 091 * <pre> 092 * BidiMap map1 = new DualHashBidiMap(); 093 * map.put("A","B"); // contains A mapped to B, as per Map 094 * map.put("A","C"); // contains A mapped to C, as per Map 095 * 096 * BidiMap map2 = new DualHashBidiMap(); 097 * map.put("A","B"); // contains A mapped to B, as per Map 098 * map.put("C","B"); // contains C mapped to B, key A is removed 099 * </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}