scolebourne 2003/10/05 13:38:56
Modified: collections/src/java/org/apache/commons/collections
BidiMap.java
Log:
Clarify the contract of the put method in BidiMaps
Revision Changes Path
1.2 +32 -2
jakarta-commons/collections/src/java/org/apache/commons/collections/BidiMap.java
Index: BidiMap.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/BidiMap.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- BidiMap.java 20 Sep 2003 20:24:30 -0000 1.1
+++ BidiMap.java 5 Oct 2003 20:38:55 -0000 1.2
@@ -73,6 +73,36 @@
public interface BidiMap extends Map {
/**
+ * 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 HashBidiMap();
+ * map.put("A","B"); // contains A mapped to B, as per Map
+ * map.put("A","C"); // contains A mapped to C, as per Map
+ *
+ * BidiMap map2 = new HashBidiMap();
+ * 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 specifed 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
+ */
+ public Object put(Object key, Object 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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
