scolebourne 2003/11/01 10:45:48 Modified: collections/src/java/org/apache/commons/collections DoubleOrderedMap.java Log: Document the existence of the new DualHashBidiMap/DualTreeBidiMap classes Revision Changes Path 1.7 +43 -34 jakarta-commons/collections/src/java/org/apache/commons/collections/DoubleOrderedMap.java Index: DoubleOrderedMap.java =================================================================== RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/DoubleOrderedMap.java,v retrieving revision 1.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- DoubleOrderedMap.java 31 Aug 2003 17:26:43 -0000 1.6 +++ DoubleOrderedMap.java 1 Nov 2003 18:45:48 -0000 1.7 @@ -71,12 +71,12 @@ * Red-Black tree-based implementation of Map. This class guarantees * that the map will be in both ascending key order and ascending * value order, sorted according to the natural order for the key's - * and value's classes.<p> - * + * and value's classes. + * <p> * This Map is intended for applications that need to be able to look * up a key-value pairing by either key or value, and need to do so - * with equal efficiency.<p> - * + * with equal efficiency. + * <p> * While that goal could be accomplished by taking a pair of TreeMaps * and redirecting requests to the appropriate TreeMap (e.g., * containsKey would be directed to the TreeMap that maps values to @@ -84,8 +84,11 @@ * to values), there are problems with that implementation, * particularly when trying to keep the two TreeMaps synchronized with * each other. And if the data contained in the TreeMaps is large, the - * cost of redundant storage becomes significant.<p> - * + * cost of redundant storage becomes significant. (See also the new + * [EMAIL PROTECTED] org.apache.commons.collections.DualTreeBidiMap DualTreeBidiMap} and + * [EMAIL PROTECTED] org.apache.commons.collections.DualHashBidiMap DualHashBidiMap} + * implementations.) + * <p> * This solution keeps the data properly synchronized and minimizes * the data storage. The red-black algorithm is based on TreeMap's, * but has been modified to simultaneously map a tree node by key and @@ -94,49 +97,52 @@ * operations (there is a savings in that the lookup of the node to be * removed only has to be performed once). And since only one node * contains the key and value, storage is significantly less than that - * required by two TreeMaps.<p> - * + * required by two TreeMaps. + * <p> * There are some limitations placed on data kept in this Map. The - * biggest one is this:<p> - * + * biggest one is this: + * <p> * When performing a put operation, neither the key nor the value may * already exist in the Map. In the java.util Map implementations * (HashMap, TreeMap), you can perform a put with an already mapped * key, and neither cares about duplicate values at all ... but this * implementation's put method with throw an IllegalArgumentException - * if either the key or the value is already in the Map.<p> - * + * if either the key or the value is already in the Map. + * <p> * Obviously, that same restriction (and consequence of failing to - * heed that restriction) applies to the putAll method.<p> - * + * heed that restriction) applies to the putAll method. + * <p> * The Map.Entry instances returned by the appropriate methods will * not allow setValue() and will throw an - * UnsupportedOperationException on attempts to call that method.<p> - * + * UnsupportedOperationException on attempts to call that method. + * <p> * New methods are added to take advantage of the fact that values are - * kept sorted independently of their keys:<p> - * + * kept sorted independently of their keys: + * <p> * Object getKeyForValue(Object value) is the opposite of get; it - * takes a value and returns its key, if any.<p> - * + * takes a value and returns its key, if any. + * <p> * Object removeValue(Object value) finds and removes the specified - * value and returns the now un-used key.<p> - * + * value and returns the now un-used key. + * <p> * Set entrySetByValue() returns the Map.Entry's in a Set whose * iterator will iterate over the Map.Entry's in ascending order by - * their corresponding values.<p> - * + * their corresponding values. + * <p> * Set keySetByValue() returns the keys in a Set whose iterator will * iterate over the keys in ascending order by their corresponding - * values.<p> - * + * values. + * <p> * Collection valuesByValue() returns the values in a Collection whose - * iterator will iterate over the values in ascending order.<p> + * iterator will iterate over the values in ascending order. * + * @see BidiMap + * @see DualTreeBidiMap + * @see DualHashBidiMap * @since Commons Collections 2.0 * @version $Revision$ $Date$ * - * @author Marc Johnson (marcj at users dot sourceforge dot net) + * @author Marc Johnson */ public final class DoubleOrderedMap extends AbstractMap { // final for performance @@ -1606,10 +1612,13 @@ * by the map, so changes to the map are reflected in the set, and * vice-versa. If the map is modified while an iteration over the * set is in progress, the results of the iteration are - * undefined. The set supports element removal, which removes the - * corresponding mapping from the map, via the Iterator.remove, - * Set.remove, removeAll, retainAll and clear operations. It does - * not support the add or addAll operations. + * undefined. + * <p> + * The set supports element removal, which removes the corresponding + * mapping from the map, via the Iterator.remove, Set.remove, removeAll, + * retainAll and clear operations. + * It does not support the add or addAll operations. + * The setValue method is not supported on the Map Entry. * * @return a set view of the mappings contained in this map. */
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]