--- jsr166/src/jsr166x/ConcurrentSkipListMap.java 2010/09/01 20:12:39 1.10 +++ jsr166/src/jsr166x/ConcurrentSkipListMap.java 2012/11/25 21:06:56 1.19 @@ -1,7 +1,7 @@ /* * Written by Doug Lea with assistance from members of JCP JSR-166 * Expert Group and released to the public domain, as explained at - * http://creativecommons.org/licenses/publicdomain + * http://creativecommons.org/publicdomain/zero/1.0/ */ package jsr166x; @@ -325,7 +325,7 @@ public class ConcurrentSkipListMap private transient DescendingEntrySet descendingEntrySet; /** - * Initialize or reset state. Needed by constructors, clone, + * Initializes or resets state. Needed by constructors, clone, * clear, readObject. and ConcurrentSkipListSet.clone. * (Note that comparator must be separately initialized.) */ @@ -414,7 +414,7 @@ public class ConcurrentSkipListMap } /** - * Return true if this node is a marker. This method isn't + * Returns true if this node is a marker. This method isn't * actually called in an any current code checking for markers * because callers will have already read value field and need * to use that read (not another done here) and so directly @@ -427,7 +427,7 @@ public class ConcurrentSkipListMap } /** - * Return true if this node is the header of base-level list. + * Returns true if this node is the header of base-level list. * @return true if this node is header node */ boolean isBaseHeader() { @@ -465,7 +465,7 @@ public class ConcurrentSkipListMap } /** - * Return value if this node contains a valid key-value pair, + * Returns value if this node contains a valid key-value pair, * else null. * @return this node's value if it isn't a marker or header or * is deleted, else null. @@ -478,8 +478,8 @@ public class ConcurrentSkipListMap } /** - * Create and return a new SnapshotEntry holding current - * mapping if this node holds a valid value, else null + * Creates and returns a new SnapshotEntry holding current + * mapping if this node holds a valid value, else null. * @return new entry or null */ SnapshotEntry createSnapshot() { @@ -696,7 +696,7 @@ public class ConcurrentSkipListMap } /** - * Compare using comparator or natural ordering. Used when the + * Compares using comparator or natural ordering. Used when the * ComparableUsingComparator approach doesn't apply. */ int compare(K k1, K k2) throws ClassCastException { @@ -708,9 +708,9 @@ public class ConcurrentSkipListMap } /** - * Return true if given key greater than or equal to least and + * Returns true if given key greater than or equal to least and * strictly less than fence, bypassing either test if least or - * fence oare null. Needed mainly in submap operations. + * fence are null. Needed mainly in submap operations. */ boolean inHalfOpenRange(K key, K least, K fence) { if (key == null) @@ -720,7 +720,7 @@ public class ConcurrentSkipListMap } /** - * Return true if given key greater than or equal to least and less + * Returns true if given key greater than or equal to least and less * or equal to fence. Needed mainly in submap operations. */ boolean inOpenRange(K key, K least, K fence) { @@ -733,7 +733,7 @@ public class ConcurrentSkipListMap /* ---------------- Traversal -------------- */ /** - * Return a base-level node with key strictly less than given key, + * Returns a base-level node with key strictly less than given key, * or the base-level header if there is no such node. Also * unlinks indexes to deleted nodes found along the way. Callers * rely on this side-effect of clearing indices to deleted nodes. @@ -766,7 +766,7 @@ public class ConcurrentSkipListMap } /** - * Return node holding key or null if no such, clearing out any + * Returns node holding key or null if no such, clearing out any * deleted nodes seen along the way. Repeatedly traverses at * base-level looking for key starting at predecessor returned * from findPredecessor, processing base-level deletions as @@ -865,7 +865,7 @@ public class ConcurrentSkipListMap } if (c == 0) { Object v = r.node.value; - return (v != null)? (V)v : getUsingFindNode(key); + return (v != null) ? (V)v : getUsingFindNode(key); } bound = rk; } @@ -878,7 +878,7 @@ public class ConcurrentSkipListMap int c = key.compareTo(nk); if (c == 0) { Object v = n.value; - return (v != null)? (V)v : getUsingFindNode(key); + return (v != null) ? (V)v : getUsingFindNode(key); } if (c < 0) return null; @@ -890,7 +890,7 @@ public class ConcurrentSkipListMap } /** - * Perform map.get via findNode. Used as a backup if doGet + * Performs map.get via findNode. Used as a backup if doGet * encounters an in-progress deletion. * @param key the key * @return the value, or null if absent @@ -965,7 +965,7 @@ public class ConcurrentSkipListMap } /** - * Return a random level for inserting a new node. + * Returns a random level for inserting a new node. * Hardwired to k=1, p=0.5, max 31. * * This uses a cheap pseudo-random function that according to @@ -987,7 +987,7 @@ public class ConcurrentSkipListMap } /** - * Create and add index nodes for given node. + * Creates and adds index nodes for given node. * @param z the node * @param level the level of the index */ @@ -1039,7 +1039,7 @@ public class ConcurrentSkipListMap } /** - * Add given index nodes from given level down to 1. + * Adds given index nodes from given level down to 1. * @param idx the topmost index node being inserted * @param h the value of head to use to insert. This must be * snapshotted by callers to provide correct insertion level @@ -1221,7 +1221,7 @@ public class ConcurrentSkipListMap } /** - * Remove first entry; return either its key or a snapshot. + * Removes first entry; return either its key or a snapshot. * @param keyOnly if true return key, else return SnapshotEntry * (This is a little ugly, but avoids code duplication.) * @return null if empty, first key if keyOnly true, else key,value entry @@ -1246,13 +1246,13 @@ public class ConcurrentSkipListMap findFirst(); // retry clearIndexToFirst(); K key = n.key; - return (keyOnly)? key : new SnapshotEntry(key, (V)v); + return keyOnly ? key : new SnapshotEntry(key, (V)v); } } /** - * Clear out index nodes associated with deleted first entry. - * Needed by doRemoveFirst + * Clears out index nodes associated with deleted first entry. + * Needed by doRemoveFirst. */ private void clearIndexToFirst() { for (;;) { @@ -1271,7 +1271,7 @@ public class ConcurrentSkipListMap } /** - * Remove first entry; return key or null if empty. + * Removes first entry; return key or null if empty. */ K pollFirstKey() { return (K)doRemoveFirst(true); @@ -1306,7 +1306,7 @@ public class ConcurrentSkipListMap Node n = b.next; for (;;) { if (n == null) - return (b.isBaseHeader())? null : b; + return b.isBaseHeader() ? null : b; Node f = n.next; // inconsistent read if (n != b.next) break; @@ -1368,7 +1368,7 @@ public class ConcurrentSkipListMap if (head.right == null) tryReduceLevel(); } - return (keyOnly)? key : new SnapshotEntry(key, (V)v); + return keyOnly ? key : new SnapshotEntry(key, (V)v); } } } @@ -1405,7 +1405,7 @@ public class ConcurrentSkipListMap } /** - * Remove last entry; return key or null if empty. + * Removes last entry; return key or null if empty. */ K pollLastKey() { return (K)doRemoveLast(true); @@ -1432,7 +1432,7 @@ public class ConcurrentSkipListMap Node n = b.next; for (;;) { if (n == null) - return ((rel & LT) == 0 || b.isBaseHeader())? null : b; + return ((rel & LT) == 0 || b.isBaseHeader()) ? null : b; Node f = n.next; if (n != b.next) // inconsistent read break; @@ -1448,7 +1448,7 @@ public class ConcurrentSkipListMap (c < 0 && (rel & LT) == 0)) return n; if ( c <= 0 && (rel & LT) != 0) - return (b.isBaseHeader())? null : b; + return b.isBaseHeader() ? null : b; b = n; n = f; } @@ -1456,7 +1456,7 @@ public class ConcurrentSkipListMap } /** - * Return SnapshotEntry for results of findNear. + * Returns SnapshotEntry for results of findNear. * @param kkey the key * @param rel the relation -- OR'ed combination of EQ, LT, GT * @return Entry fitting relation, or null if no such @@ -1473,21 +1473,21 @@ public class ConcurrentSkipListMap } /** - * Return ceiling, or first node if key is null + * Returns ceiling, or first node if key is null. */ Node findCeiling(K key) { - return (key == null)? findFirst() : findNear(key, GT|EQ); + return (key == null) ? findFirst() : findNear(key, GT|EQ); } /** - * Return lower node, or last node if key is null + * Returns lower node, or last node if key is null. */ Node findLower(K key) { - return (key == null)? findLast() : findNear(key, LT); + return (key == null) ? findLast() : findNear(key, LT); } /** - * Return SnapshotEntry or key for results of findNear ofter screening + * Returns SnapshotEntry or key for results of findNear ofter screening * to ensure result is in given range. Needed by submaps. * @param kkey the key * @param rel the relation -- OR'ed combination of EQ, LT, GT @@ -1513,12 +1513,12 @@ public class ConcurrentSkipListMap K k = n.key; V v = n.getValidValue(); if (v != null) - return keyOnly? k : new SnapshotEntry(k, v); + return keyOnly ? k : new SnapshotEntry(k, v); } } /** - * Find and remove least element of subrange. + * Finds and removes least element of subrange. * @param least minimum allowed key value * @param fence key greater than maximum allowed key value * @param keyOnly if true return key, else return SnapshotEntry @@ -1534,12 +1534,12 @@ public class ConcurrentSkipListMap return null; V v = doRemove(k, null); if (v != null) - return (keyOnly)? k : new SnapshotEntry(k, v); + return keyOnly ? k : new SnapshotEntry(k, v); } } /** - * Find and remove greatest element of subrange. + * Finds and removes greatest element of subrange. * @param least minimum allowed key value * @param fence key greater than maximum allowed key value * @param keyOnly if true return key, else return SnapshotEntry @@ -1555,7 +1555,7 @@ public class ConcurrentSkipListMap return null; V v = doRemove(k, null); if (v != null) - return (keyOnly)? k : new SnapshotEntry(k, v); + return keyOnly ? k : new SnapshotEntry(k, v); } } @@ -1689,7 +1689,7 @@ public class ConcurrentSkipListMap /* ---------------- Serialization -------------- */ /** - * Save the state of the Map instance to a stream. + * Saves the state of the Map instance to a stream. * * @serialData The key (Object) and value (Object) for each * key-value mapping represented by the Map, followed by @@ -1714,7 +1714,7 @@ public class ConcurrentSkipListMap } /** - * Reconstitute the Map instance from a stream. + * Reconstitutes the Map instance from a stream. */ private void readObject(final java.io.ObjectInputStream s) throws java.io.IOException, ClassNotFoundException { @@ -1883,7 +1883,7 @@ public class ConcurrentSkipListMap if (n.getValidValue() != null) ++count; } - return (count >= Integer.MAX_VALUE)? Integer.MAX_VALUE : (int)count; + return (count >= Integer.MAX_VALUE) ? Integer.MAX_VALUE : (int)count; } /** @@ -2094,9 +2094,9 @@ public class ConcurrentSkipListMap * This is equivalent to * 
      *   if (!map.containsKey(key))
-     *      return map.put(key, value);
+     *     return map.put(key, value);
      *   else
-     *      return map.get(key);
+     *     return map.get(key);
      *
* except that the action is performed atomically. * @param key key with which the specified value is to be associated. @@ -2115,7 +2115,7 @@ public class ConcurrentSkipListMap } /** - * Remove entry for key only if currently mapped to given value. + * Removes entry for key only if currently mapped to given value. * Acts as * 
      *  if ((map.containsKey(key) && map.get(key).equals(value)) {
@@ -2250,7 +2250,7 @@ public class ConcurrentSkipListMap
      * fromKey and toKey are equal, the returned sorted map
      * is empty.)  The returned sorted map is backed by this map, so changes
      * in the returned sorted map are reflected in this map, and vice-versa.
-
+     *
      * @param fromKey low endpoint (inclusive) of the subMap.
      * @param toKey high endpoint (exclusive) of the subMap.
      *
@@ -2305,7 +2305,7 @@ public class ConcurrentSkipListMap
      * Comparable).
      * @throws NullPointerException if fromKey is null.
      */
-    public ConcurrentNavigableMap  tailMap(K fromKey) {
+    public ConcurrentNavigableMap tailMap(K fromKey) {
         if (fromKey == null)
             throw new NullPointerException();
         return new ConcurrentSkipListSubMap(this, fromKey, null);
@@ -2343,7 +2343,7 @@ public class ConcurrentSkipListMap
      */
     public K ceilingKey(K key) {
         Node n = findNear(key, GT|EQ);
-        return (n == null)? null : n.key;
+        return (n == null) ? null : n.key;
     }
 
     /**
@@ -2376,7 +2376,7 @@ public class ConcurrentSkipListMap
      */
     public K lowerKey(K key) {
         Node n = findNear(key, LT);
-        return (n == null)? null : n.key;
+        return (n == null) ? null : n.key;
     }
 
     /**
@@ -2410,7 +2410,7 @@ public class ConcurrentSkipListMap
      */
     public K floorKey(K key) {
         Node n = findNear(key, LT|EQ);
-        return (n == null)? null : n.key;
+        return (n == null) ? null : n.key;
     }
 
     /**
@@ -2443,7 +2443,7 @@ public class ConcurrentSkipListMap
      */
     public K higherKey(K key) {
         Node n = findNear(key, GT);
-        return (n == null)? null : n.key;
+        return (n == null) ? null : n.key;
     }
 
     /**
@@ -3050,7 +3050,7 @@ public class ConcurrentSkipListMap
          * Creates a new submap.
          * @param least inclusive least value, or null if from start
          * @param fence exclusive upper bound or null if to end
-         * @throws IllegalArgumentException if least and fence nonnull
+         * @throws IllegalArgumentException if least and fence non-null
          *  and least greater than fence
          */
         ConcurrentSkipListSubMap(ConcurrentSkipListMap map,
@@ -3128,7 +3128,7 @@ public class ConcurrentSkipListMap
 
         public V get(Object key) {
             K k = (K)key;
-            return ((!inHalfOpenRange(k)) ? null : m.get(k));
+            return (!inHalfOpenRange(k)) ? null : m.get(k);
         }
 
         public V put(K key, V value) {
@@ -3138,7 +3138,7 @@ public class ConcurrentSkipListMap
 
         public V remove(Object key) {
             K k = (K)key;
-            return (!inHalfOpenRange(k))? null : m.remove(k);
+            return (!inHalfOpenRange(k)) ? null : m.remove(k);
         }
 
         public int size() {
@@ -3149,7 +3149,8 @@ public class ConcurrentSkipListMap
                 if (n.getValidValue() != null)
                     ++count;
             }
-            return count >= Integer.MAX_VALUE? Integer.MAX_VALUE : (int)count;
+            return (count >= Integer.MAX_VALUE) ?
+                Integer.MAX_VALUE : (int)count;
         }
 
         public boolean isEmpty() {
@@ -3240,7 +3241,7 @@ public class ConcurrentSkipListMap
             return new ConcurrentSkipListSubMap(m, least, toKey);
         }
 
-        public  ConcurrentNavigableMap tailMap(K fromKey) {
+        public ConcurrentNavigableMap tailMap(K fromKey) {
             if (fromKey == null)
                 throw new NullPointerException();
             if (!inOpenRange(fromKey))