1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package net.sf.collections15;
17
18 /***
19 * Defines a map that allows bidirectional lookup between key and values.
20 * <p/>
21 * This extended <code>Map</code> represents a mapping where a key may lookup a
22 * value and a value may lookup a key with equal ease. This interface extends
23 * <code>Map</code> and so may be used anywhere a map is required. The interface
24 * provides an inverse map view, enabling full access to both directions of the
25 * <code>BidiMap</code>.
26 * <p/>
27 * Implementations should allow a value to be looked up from a key and a key to
28 * be looked up from a value with equal performance.
29 * <p/>
30 * This map enforces the restriction that there is a 1:1 relation between keys
31 * and values, meaning that multiple keys cannot map to the same value. This is
32 * required so that "inverting" the map results in a map without duplicate keys.
33 * See the {@link #put} method description for more information.
34 *
35 * @author Stephen Colebourne
36 * @version $Revision: 1.2 $ $Date: 2004/10/17 01:02:42 $
37 * @since Commons Collections15 1.0
38 */
39 public interface BidiMap <K, V> extends IterableMap<K, V>
40 {
41
42 /***
43 * Obtains a <code>MapIterator</code> over the map.
44 * <p/>
45 * A map iterator is an efficient way of iterating over maps. It does not
46 * require that the map is stored using Map Entry objects which can increase
47 * performance.
48 * <pre>
49 * BidiMap map = new DualHashBidiMap();
50 * MapIterator it = map.mapIterator();
51 * while (it.hasNext()) {
52 * Object key = it.next();
53 * Object value = it.getValue();
54 * it.setValue("newValue");
55 * }
56 * </pre>
57 *
58 * @return a map iterator
59 */
60 MapIterator<K, V> mapIterator();
61
62 /***
63 * Puts the key-value pair into the map, replacing any previous pair.
64 * <p/>
65 * When adding a key-value pair, the value may already exist in the map
66 * against a different key. That mapping is removed, to ensure that the
67 * value only occurs once in the inverse map.
68 * <pre>
69 * BidiMap map1 = new DualHashBidiMap();
70 * map.put("A","B"); // contains A mapped to B, as per Map
71 * map.put("A","C"); // contains A mapped to C, as per Map
72 * <p/>
73 * BidiMap map2 = new DualHashBidiMap();
74 * map.put("A","B"); // contains A mapped to B, as per Map
75 * map.put("C","B"); // contains C mapped to B, key A is removed
76 * </pre>
77 *
78 * @param key the key to store
79 * @param value the value to store
80 *
81 * @return the previous value mapped to this key
82 *
83 * @throws UnsupportedOperationException if the <code>put</code> method is
84 * not supported
85 * @throws ClassCastException (optional) if the map limits the
86 * type of the value and the specified
87 * value is inappropriate
88 * @throws IllegalArgumentException (optional) if the map limits the
89 * values in some way and the value
90 * was invalid
91 * @throws NullPointerException (optional) if the map limits the
92 * values to non-null and null was
93 * specified
94 */
95 V put(K key, V value);
96
97 /***
98 * Gets the key that is currently mapped to the specified value.
99 * <p/>
100 * If the value is not contained in the map, <code>null</code> is returned.
101 * <p/>
102 * Implementations should seek to make this method perform equally as well
103 * as <code>get(Object)</code>.
104 *
105 * @param value the value to find the key for
106 *
107 * @return the mapped key, or <code>null</code> if not found
108 *
109 * @throws ClassCastException (optional) if the map limits the type of the
110 * value and the specified value is
111 * inappropriate
112 * @throws NullPointerException (optional) if the map limits the values to
113 * non-null and null was specified
114 */
115 K getKey(V value);
116
117 /***
118 * Removes the key-value pair that is currently mapped to the specified
119 * value (optional operation).
120 * <p/>
121 * If the value is not contained in the map, <code>null</code> is returned.
122 * <p/>
123 * Implementations should seek to make this method perform equally as well
124 * as <code>remove(Object)</code>.
125 *
126 * @param value the value to find the key-value pair for
127 *
128 * @return the key that was removed, <code>null</code> if nothing removed
129 *
130 * @throws ClassCastException (optional) if the map limits the
131 * type of the value and the specified
132 * value is inappropriate
133 * @throws NullPointerException (optional) if the map limits the
134 * values to non-null and null was
135 * specified
136 * @throws UnsupportedOperationException if this method is not supported by
137 * the implementation
138 */
139 K removeValue(V value);
140
141 /***
142 * Gets a view of this map where the keys and values are reversed.
143 * <p/>
144 * Changes to one map will be visible in the other and vice versa. This
145 * enables both directions of the map to be accessed as a <code>Map</code>.
146 * <p/>
147 * Implementations should seek to avoid creating a new object every time
148 * this method is called. See <code>AbstractMap.values()</code> etc. Calling
149 * this method on the inverse map should return the original.
150 *
151 * @return an inverted bidirectional map
152 */
153 BidiMap<V, K> inverseBidiMap();
154
155 }