commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections DoubleOrderedMap.java
Date Sat, 01 Nov 2003 18:45:48 GMT
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
  + * {@link org.apache.commons.collections.DualTreeBidiMap DualTreeBidiMap} and
  + * {@link 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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message