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.collections;
18
19 /**
20 * Defines a map that allows bidirectional lookup between key and values.
21 * <p>
22 * This extended <code>Map</code> represents a mapping where a key may
23 * lookup a value and a value may lookup a key with equal ease.
24 * This interface extends <code>Map</code> and so may be used anywhere a map
25 * is required. The interface provides an inverse map view, enabling
26 * full access to both directions of the <code>BidiMap</code>.
27 * <p>
28 * Implementations should allow a value to be looked up from a key and
29 * a key to be looked up from a value with equal performance.
30 * <p>
31 * This map enforces the restriction that there is a 1:1 relation between
32 * keys and values, meaning that multiple keys cannot map to the same value.
33 * This is required so that "inverting" the map results in a map without
34 * duplicate keys. See the {@link #put} method description for more information.
35 *
36 * @param <K> the type of the keys in the map
37 * @param <V> the type of the values in the map
38 *
39 * @since 3.0
40 * @version $Id: BidiMap.java 1361710 2012-07-15 15:00:21Z tn $
41 */
42 public interface BidiMap<K, V> extends IterableMap<K, V> {
43
44 /**
45 * Puts the key-value pair into the map, replacing any previous pair.
46 * <p>
47 * When adding a key-value pair, the value may already exist in the map
48 * against a different key. That mapping is removed, to ensure that the
49 * value only occurs once in the inverse map.
50 * <pre>
51 * BidiMap map1 = new DualHashBidiMap();
52 * map.put("A","B"); // contains A mapped to B, as per Map
53 * map.put("A","C"); // contains A mapped to C, as per Map
54 *
55 * BidiMap map2 = new DualHashBidiMap();
56 * map.put("A","B"); // contains A mapped to B, as per Map
57 * map.put("C","B"); // contains C mapped to B, key A is removed
58 * </pre>
59 *
60 * @param key the key to store
61 * @param value the value to store
62 * @return the previous value mapped to this key
63 *
64 * @throws UnsupportedOperationException if the <code>put</code> method is not supported
65 * @throws ClassCastException (optional) if the map limits the type of the
66 * value and the specified value is inappropriate
67 * @throws IllegalArgumentException (optional) if the map limits the values
68 * in some way and the value was invalid
69 * @throws NullPointerException (optional) if the map limits the values to
70 * non-null and null was specified
71 */
72 V put(K key, V value);
73
74 /**
75 * Gets the key that is currently mapped to the specified value.
76 * <p>
77 * If the value is not contained in the map, <code>null</code> is returned.
78 * <p>
79 * Implementations should seek to make this method perform equally as well
80 * as <code>get(Object)</code>.
81 *
82 * @param value the value to find the key for
83 * @return the mapped key, or <code>null</code> if not found
84 *
85 * @throws ClassCastException (optional) if the map limits the type of the
86 * value and the specified value is inappropriate
87 * @throws NullPointerException (optional) if the map limits the values to
88 * non-null and null was specified
89 */
90 K getKey(Object value);
91
92 /**
93 * Removes the key-value pair that is currently mapped to the specified
94 * value (optional operation).
95 * <p>
96 * If the value is not contained in the map, <code>null</code> is returned.
97 * <p>
98 * Implementations should seek to make this method perform equally as well
99 * as <code>remove(Object)</code>.
100 *
101 * @param value the value to find the key-value pair for
102 * @return the key that was removed, <code>null</code> if nothing removed
103 *
104 * @throws ClassCastException (optional) if the map limits the type of the
105 * value and the specified value is inappropriate
106 * @throws NullPointerException (optional) if the map limits the values to
107 * non-null and null was specified
108 * @throws UnsupportedOperationException if this method is not supported
109 * by the implementation
110 */
111 K removeValue(Object value);
112
113 /**
114 * Gets a view of this map where the keys and values are reversed.
115 * <p>
116 * Changes to one map will be visible in the other and vice versa.
117 * This enables both directions of the map to be accessed as a <code>Map</code>.
118 * <p>
119 * Implementations should seek to avoid creating a new object every time this
120 * method is called. See <code>AbstractMap.values()</code> etc. Calling this
121 * method on the inverse map should return the original.
122 *
123 * @return an inverted bidirectional map
124 */
125 BidiMap<V, K> inverseBidiMap();
126
127 }