Java tutorial
// GenericsNote: Converted. /* * Copyright 2003-2004 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.collections15; import java.util.Set; /** * Defines a map that allows bidirectional lookup between key and values. * <p/> * This extended <code>Map</code> represents a mapping where a key may * lookup a value and a value may lookup a key with equal ease. * This interface extends <code>Map</code> and so may be used anywhere a map * is required. The interface provides an inverse map view, enabling * full access to both directions of the <code>BidiMap</code>. * <p/> * Implementations should allow a value to be looked up from a key and * a key to be looked up from a value with equal performance. * <p/> * This map enforces the restriction that there is a 1:1 relation between * keys and values, meaning that multiple keys cannot map to the same value. * This is required so that "inverting" the map results in a map without * duplicate keys. See the {@link #put} method description for more information. * * @author Matt Hall, John Watkinson, Stephen Colebourne * @version $Revision: 1.1 $ $Date: 2005/10/11 17:05:19 $ * @since Commons Collections 3.0 */ public interface BidiMap<K, V> extends IterableMap<K, V> { /** * Obtains a <code>MapIterator</code> over the map. * <p/> * A map iterator is an efficient way of iterating over maps. * It does not require that the map is stored using Map Entry objects * which can increase performance. * <pre> * BidiMap map = new DualHashBidiMap(); * MapIterator it = map.mapIterator(); * while (it.hasNext()) { * Object key = it.next(); * Object value = it.getValue(); * it.setValue("newValue"); * } * </pre> * * @return a map iterator */ MapIterator<K, V> mapIterator(); /** * Puts the key-value pair into the map, replacing any previous pair. * <p/> * When adding a key-value pair, the value may already exist in the map * against a different key. That mapping is removed, to ensure that the * value only occurs once in the inverse map. * <pre> * BidiMap map1 = new DualHashBidiMap(); * map.put("A","B"); // contains A mapped to B, as per Map * map.put("A","C"); // contains A mapped to C, as per Map * <p/> * BidiMap map2 = new DualHashBidiMap(); * map.put("A","B"); // contains A mapped to B, as per Map * map.put("C","B"); // contains C mapped to B, key A is removed * </pre> * * @param key the key to store * @param value the value to store * @return the previous value mapped to this key * @throws UnsupportedOperationException if the <code>put</code> method is not supported * @throws ClassCastException (optional) if the map limits the type of the * value and the specified value is inappropriate * @throws IllegalArgumentException (optional) if the map limits the values * in some way and the value was invalid * @throws NullPointerException (optional) if the map limits the values to * non-null and null was specified */ V put(K key, V value); /** * Gets the key that is currently mapped to the specified value. * <p/> * If the value is not contained in the map, <code>null</code> is returned. * <p/> * Implementations should seek to make this method perform equally as well * as <code>get(Object)</code>. * * @param value the value to find the key for * @return the mapped key, or <code>null</code> if not found * @throws ClassCastException (optional) if the map limits the type of the * value and the specified value is inappropriate * @throws NullPointerException (optional) if the map limits the values to * non-null and null was specified */ K getKey(Object value); /** * Removes the key-value pair that is currently mapped to the specified * value (optional operation). * <p/> * If the value is not contained in the map, <code>null</code> is returned. * <p/> * Implementations should seek to make this method perform equally as well * as <code>remove(Object)</code>. * * @param value the value to find the key-value pair for * @return the key that was removed, <code>null</code> if nothing removed * @throws ClassCastException (optional) if the map limits the type of the * value and the specified value is inappropriate * @throws NullPointerException (optional) if the map limits the values to * non-null and null was specified * @throws UnsupportedOperationException if this method is not supported * by the implementation */ K removeValue(Object value); /** * Gets a view of this map where the keys and values are reversed. * <p/> * Changes to one map will be visible in the other and vice versa. * This enables both directions of the map to be accessed as a <code>Map</code>. * <p/> * Implementations should seek to avoid creating a new object every time this * method is called. See <code>AbstractMap.values()</code> etc. Calling this * method on the inverse map should return the original. * * @return an inverted bidirectional map */ BidiMap<V, K> inverseBidiMap(); /** * Returns a set view of the values contained in this BidiMap. The * set is backed by the map, so changes to the map are reflected in * the collection, and vice-versa. If the map is modified while an * iteration over the collection is in progress (except through the * iterator's own <tt>remove</tt> operation), the results of the * iteration are undefined. The collection supports element removal, * which removes the corresponding mapping from the map, via the * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>, * <tt>removeAll</tt>, <tt>retainAll</tt> and <tt>clear</tt> operations. * It does not support the add or <tt>addAll</tt> operations. * * @return a Set view of the values contained in this map. */ Set<V> values(); }