--- jsr166/src/jsr166x/ConcurrentSkipListMap.java 2011/10/25 18:46:37 1.15 +++ jsr166/src/jsr166x/ConcurrentSkipListMap.java 2015/07/27 03:06:08 1.34 @@ -20,8 +20,8 @@ import java.util.concurrent.atomic.*; *

This class implements a concurrent variant of SkipLists providing * expected average log(n) time cost for the - * containsKey, get, put and - * remove operations and their variants. Insertion, removal, + * {@code containsKey}, {@code get}, {@code put} and + * {@code remove} operations and their variants. Insertion, removal, * update, and access operations safely execute concurrently by * multiple threads. Iterators are weakly consistent, returning * elements reflecting the state of the map at some point at or since @@ -30,27 +30,27 @@ import java.util.concurrent.atomic.*; * other operations. Ascending key ordered views and their iterators * are faster than descending ones. * - *

All Map.Entry pairs returned by methods in this class + *

All {@code Map.Entry} pairs returned by methods in this class * and its views represent snapshots of mappings at the time they were - * produced. They do not support the Entry.setValue + * produced. They do not support the {@code Entry.setValue} * method. (Note however that it is possible to change mappings in the - * associated map using put, putIfAbsent, or - * replace, depending on exactly which effect you need.) + * associated map using {@code put}, {@code putIfAbsent}, or + * {@code replace}, depending on exactly which effect you need.) * - *

Beware that, unlike in most collections, the size + *

Beware that, unlike in most collections, the {@code size} * method is not a constant-time operation. Because of the * asynchronous nature of these maps, determining the current number * of elements requires a traversal of the elements. Additionally, - * the bulk operations putAll, equals, and - * clear are not guaranteed to be performed + * the bulk operations {@code putAll}, {@code equals}, and + * {@code clear} are not guaranteed to be performed * atomically. For example, an iterator operating concurrently with a - * putAll operation might view only some of the added + * {@code putAll} operation might view only some of the added * elements. * *

This class and its views and iterators implement all of the * optional methods of the {@link Map} and {@link Iterator} * interfaces. Like most other concurrent collections, this class does - * not permit the use of null keys or values because some + * not permit the use of {@code null} keys or values because some * null return values cannot be reliably distinguished from the * absence of elements. * @@ -212,7 +212,7 @@ public class ConcurrentSkipListMap * highly contended cases. * * Unlike most skip-list implementations, index insertion and - * deletion here require a separate traversal pass occuring after + * deletion here require a separate traversal pass occurring after * the base-level action, to add or remove index nodes. This adds * to single-threaded overhead, but improves contended * multithreaded performance by narrowing interference windows, @@ -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,12 +414,12 @@ 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 * test if value points to node. - * @param n a possibly null reference to a node + * * @return true if this node is a marker node */ boolean isMarker() { @@ -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,10 +465,10 @@ 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. + * is deleted, else null */ V getValidValue() { Object v = value; @@ -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() { @@ -507,7 +507,7 @@ public class ConcurrentSkipListMap volatile Index right; /** - * Creates index node with given values + * Creates index node with given values. */ Index(Node node, Index down, Index right) { this.node = node; @@ -580,7 +580,7 @@ public class ConcurrentSkipListMap /** * An immutable representation of a key-value mapping as it * existed at some point in time. This class does not - * support the Map.Entry.setValue method. + * support the {@code Map.Entry.setValue} method. */ static class SnapshotEntry implements Map.Entry { private final K key; @@ -599,7 +599,7 @@ public class ConcurrentSkipListMap /** * Returns the key corresponding to this entry. * - * @return the key corresponding to this entry. + * @return the key corresponding to this entry */ public K getKey() { return key; @@ -608,15 +608,15 @@ public class ConcurrentSkipListMap /** * Returns the value corresponding to this entry. * - * @return the value corresponding to this entry. + * @return the value corresponding to this entry */ public V getValue() { return value; } /** - * Always fails, throwing UnsupportedOperationException. - * @throws UnsupportedOperationException always. + * Always fails, throwing {@code UnsupportedOperationException}. + * @throws UnsupportedOperationException always */ public V setValue(V value) { throw new UnsupportedOperationException(); @@ -644,9 +644,9 @@ public class ConcurrentSkipListMap /** * Returns a String consisting of the key followed by an - * equals sign ("=") followed by the associated + * equals sign ({@code "="}) followed by the associated * value. - * @return a String representation of this entry. + * @return a String representation of this entry */ public String toString() { return getKey() + "=" + getValue(); @@ -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 @@ -807,7 +807,7 @@ public class ConcurrentSkipListMap * were performed. * * @param key the key - * @return node holding key, or null if no such. + * @return node holding key, or null if no such */ private Node findNode(Comparable key) { for (;;) { @@ -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 @@ -917,7 +917,7 @@ public class ConcurrentSkipListMap * Main insertion method. Adds element if not present, or * replaces value if present and onlyIfAbsent is false. * @param kkey the key - * @param value the value that must be associated with key + * @param value the value that must be associated with key * @param onlyIfAbsent if should not insert if already present * @return the old value, or null if newly inserted */ @@ -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,10 +1039,10 @@ 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 + * snapshotted by callers to provide correct insertion level. * @param indexLevel the level of the index */ private void addIndex(Index idx, HeadIndex h, int indexLevel) { @@ -1196,7 +1196,7 @@ public class ConcurrentSkipListMap } /** - * Version of remove with boolean return. Needed by view classes + * Version of remove with boolean return. Needed by view classes. */ boolean removep(Object key) { return doRemove(key, null) != null; @@ -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 @@ -1251,8 +1251,8 @@ public class ConcurrentSkipListMap } /** - * 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 (;;) { @@ -1270,8 +1270,8 @@ 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); @@ -1378,7 +1378,7 @@ public class ConcurrentSkipListMap * last valid node. Needed by doRemoveLast. It is possible that * all successors of returned node will have been deleted upon * return, in which case this method can be retried. - * @return likely predecessor of last node. + * @return likely predecessor of last node */ private Node findPredecessorOfLast() { for (;;) { @@ -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); @@ -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,28 +1473,28 @@ public class ConcurrentSkipListMap } /** - * Return ceiling, or first node if key is null + * Returns ceiling, or first node if key is {@code null}. */ Node findCeiling(K key) { 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 {@code null}. */ Node findLower(K key) { 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 * @param least minimum allowed key value * @param fence key greater than maximum allowed key value * @param keyOnly if true return key, else return SnapshotEntry - * @return Key or Entry fitting relation, or null if no such + * @return Key or Entry fitting relation, or {@code null} if no such */ Object getNear(K kkey, int rel, K least, K fence, boolean keyOnly) { K key = kkey; @@ -1518,11 +1518,11 @@ public class ConcurrentSkipListMap } /** - * 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 - * @return least Key or Entry, or null if no such + * @return least Key or Entry, or {@code null} if no such */ Object removeFirstEntryOfSubrange(K least, K fence, boolean keyOnly) { for (;;) { @@ -1539,11 +1539,11 @@ public class ConcurrentSkipListMap } /** - * 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 - * @return least Key or Entry, or null if no such + * @return least Key or Entry, or {@code null} if no such */ Object removeLastEntryOfSubrange(K least, K fence, boolean keyOnly) { for (;;) { @@ -1574,7 +1574,7 @@ public class ConcurrentSkipListMap * Constructs a new empty map, sorted according to the given comparator. * * @param c the comparator that will be used to sort this map. A - * null value indicates that the keys' natural + * {@code null} value indicates that the keys' natural * ordering should be used. */ public ConcurrentSkipListMap(Comparator c) { @@ -1586,10 +1586,10 @@ public class ConcurrentSkipListMap * Constructs a new map containing the same mappings as the given map, * sorted according to the keys' natural order. * - * @param m the map whose mappings are to be placed in this map. + * @param m the map whose mappings are to be placed in this map * @throws ClassCastException if the keys in m are not Comparable, or - * are not mutually comparable. - * @throws NullPointerException if the specified map is null. + * are not mutually comparable + * @throws NullPointerException if the specified map is {@code null} */ public ConcurrentSkipListMap(Map m) { this.comparator = null; @@ -1599,11 +1599,11 @@ public class ConcurrentSkipListMap /** * Constructs a new map containing the same mappings as the given - * SortedMap, sorted according to the same ordering. + * {@code SortedMap}, sorted according to the same ordering. * @param m the sorted map whose mappings are to be placed in this - * map, and whose comparator is to be used to sort this map. + * map, and whose comparator is to be used to sort this map * @throws NullPointerException if the specified sorted map is - * null. + * {@code null} */ public ConcurrentSkipListMap(SortedMap m) { this.comparator = m.comparator(); @@ -1612,10 +1612,10 @@ public class ConcurrentSkipListMap } /** - * Returns a shallow copy of this Map instance. (The keys and + * Returns a shallow copy of this {@code Map} instance. (The keys and * values themselves are not cloned.) * - * @return a shallow copy of this Map. + * @return a shallow copy of this Map */ public Object clone() { ConcurrentSkipListMap clone = null; @@ -1689,11 +1689,11 @@ public class ConcurrentSkipListMap /* ---------------- Serialization -------------- */ /** - * Saves the state of the Map instance to a stream. + * Saves the state of the {@code Map} instance to a stream. * * @serialData The key (Object) and value (Object) for each * key-value mapping represented by the Map, followed by - * null. The key-value mappings are emitted in key-order + * {@code null}. The key-value mappings are emitted in key-order * (as determined by the Comparator, or by the keys' natural * ordering if no Comparator). */ @@ -1714,7 +1714,7 @@ public class ConcurrentSkipListMap } /** - * Reconstitutes the Map instance from a stream. + * Reconstitutes the {@code Map} instance from a stream. */ private void readObject(final java.io.ObjectInputStream s) throws java.io.IOException, ClassNotFoundException { @@ -1777,14 +1777,14 @@ public class ConcurrentSkipListMap /* ------ Map API methods ------ */ /** - * Returns true if this map contains a mapping for the specified + * Returns {@code true} if this map contains a mapping for the specified * key. - * @param key key whose presence in this map is to be tested. - * @return true if this map contains a mapping for the - * specified key. + * @param key key whose presence in this map is to be tested + * @return {@code true} if this map contains a mapping for the + * specified key * @throws ClassCastException if the key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if the key is null. + * currently in the map + * @throws NullPointerException if the key is {@code null} */ public boolean containsKey(Object key) { return doGet(key) != null; @@ -1792,14 +1792,14 @@ public class ConcurrentSkipListMap /** * Returns the value to which this map maps the specified key. Returns - * null if the map contains no mapping for this key. + * {@code null} if the map contains no mapping for this key. * - * @param key key whose associated value is to be returned. + * @param key key whose associated value is to be returned * @return the value to which this map maps the specified key, or - * null if the map contains no mapping for the key. + * {@code null} if the map contains no mapping for the key * @throws ClassCastException if the key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if the key is null. + * currently in the map + * @throws NullPointerException if the key is {@code null} */ public V get(Object key) { return doGet(key); @@ -1810,14 +1810,14 @@ public class ConcurrentSkipListMap * If the map previously contained a mapping for this key, the old * value is replaced. * - * @param key key with which the specified value is to be associated. - * @param value value to be associated with the specified key. + * @param key key with which the specified value is to be associated + * @param value value to be associated with the specified key * - * @return previous value associated with specified key, or null - * if there was no mapping for key. + * @return previous value associated with specified key, or {@code null} + * if there was no mapping for key * @throws ClassCastException if the key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if the key or value are null. + * currently in the map + * @throws NullPointerException if the key or value are {@code null} */ public V put(K key, V value) { if (value == null) @@ -1829,26 +1829,26 @@ public class ConcurrentSkipListMap * Removes the mapping for this key from this Map if present. * * @param key key for which mapping should be removed - * @return previous value associated with specified key, or null - * if there was no mapping for key. + * @return previous value associated with specified key, or {@code null} + * if there was no mapping for key * * @throws ClassCastException if the key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if the key is null. + * currently in the map + * @throws NullPointerException if the key is {@code null} */ public V remove(Object key) { return doRemove(key, null); } /** - * Returns true if this map maps one or more keys to the + * Returns {@code true} if this map maps one or more keys to the * specified value. This operation requires time linear in the * Map size. * - * @param value value whose presence in this Map is to be tested. - * @return true if a mapping to value exists; - * false otherwise. - * @throws NullPointerException if the value is null. + * @param value value whose presence in this Map is to be tested + * @return {@code true} if a mapping to {@code value} exists; + * {@code false} otherwise + * @throws NullPointerException if the value is {@code null} */ public boolean containsValue(Object value) { if (value == null) @@ -1863,8 +1863,8 @@ public class ConcurrentSkipListMap /** * Returns the number of elements in this map. If this map - * contains more than Integer.MAX_VALUE elements, it - * returns Integer.MAX_VALUE. + * contains more than {@code Integer.MAX_VALUE} elements, it + * returns {@code Integer.MAX_VALUE}. * *

Beware that, unlike in most collections, this method is * NOT a constant-time operation. Because of the @@ -1875,7 +1875,7 @@ public class ConcurrentSkipListMap * will be inaccurate. Thus, this method is typically not very * useful in concurrent applications. * - * @return the number of elements in this map. + * @return the number of elements in this map */ public int size() { long count = 0; @@ -1887,8 +1887,8 @@ public class ConcurrentSkipListMap } /** - * Returns true if this map contains no key-value mappings. - * @return true if this map contains no key-value mappings. + * Returns {@code true} if this map contains no key-value mappings. + * @return {@code true} if this map contains no key-value mappings */ public boolean isEmpty() { return findFirst() == null; @@ -1905,17 +1905,17 @@ public class ConcurrentSkipListMap * Returns a set view of the keys contained in this map. The set is * backed by the map, so changes to the map are reflected in the set, and * vice-versa. The set supports element removal, which removes the - * corresponding mapping from this map, via the Iterator.remove, - * Set.remove, removeAll, retainAll, and - * clear operations. It does not support the add or - * addAll operations. - * The view's iterator is a "weakly consistent" iterator that + * corresponding mapping from this map, via the {@code Iterator.remove}, + * {@code Set.remove}, {@code removeAll}, {@code retainAll}, and + * {@code clear} operations. It does not support the {@code add} or + * {@code addAll} operations. + * The view's {@code iterator} is a "weakly consistent" iterator that * will never throw {@link java.util.ConcurrentModificationException}, * and guarantees to traverse elements as they existed upon * construction of the iterator, and may (but is not guaranteed to) * reflect any modifications subsequent to construction. * - * @return a set view of the keys contained in this map. + * @return a set view of the keys contained in this map */ public Set keySet() { /* @@ -1936,17 +1936,17 @@ public class ConcurrentSkipListMap * descending order. The set is backed by the map, so changes to * the map are reflected in the set, and vice-versa. The set * supports element removal, which removes the corresponding - * mapping from this map, via the Iterator.remove, - * Set.remove, removeAll, retainAll, - * and clear operations. It does not support the - * add or addAll operations. The view's - * iterator is a "weakly consistent" iterator that will + * mapping from this map, via the {@code Iterator.remove}, + * {@code Set.remove}, {@code removeAll}, {@code retainAll}, + * and {@code clear} operations. It does not support the + * {@code add} or {@code addAll} operations. The view's + * {@code iterator} is a "weakly consistent" iterator that will * never throw {@link java.util.ConcurrentModificationException}, * and guarantees to traverse elements as they existed upon * construction of the iterator, and may (but is not guaranteed * to) reflect any modifications subsequent to construction. * - * @return a set view of the keys contained in this map. + * @return a set view of the keys contained in this map */ public Set descendingKeySet() { /* @@ -1967,18 +1967,18 @@ public class ConcurrentSkipListMap * The collection is backed by the map, so changes to the map are * reflected in the collection, and vice-versa. The collection * supports element removal, which removes the corresponding - * mapping from this map, via the Iterator.remove, - * Collection.remove, removeAll, - * retainAll, and clear operations. It does not - * support the add or addAll operations. The - * view's iterator is a "weakly consistent" iterator that + * mapping from this map, via the {@code Iterator.remove}, + * {@code Collection.remove}, {@code removeAll}, + * {@code retainAll}, and {@code clear} operations. It does not + * support the {@code add} or {@code addAll} operations. The + * view's {@code iterator} is a "weakly consistent" iterator that * will never throw {@link * java.util.ConcurrentModificationException}, and guarantees to * traverse elements as they existed upon construction of the * iterator, and may (but is not guaranteed to) reflect any * modifications subsequent to construction. * - * @return a collection view of the values contained in this map. + * @return a collection view of the values contained in this map */ public Collection values() { Values vs = values; @@ -1988,24 +1988,24 @@ public class ConcurrentSkipListMap /** * Returns a collection view of the mappings contained in this * map. Each element in the returned collection is a - * Map.Entry. The collection is backed by the map, so + * {@code Map.Entry}. The collection is backed by the map, so * changes to the map are reflected in the collection, and * vice-versa. The collection supports element removal, which * removes the corresponding mapping from the map, via the - * Iterator.remove, Collection.remove, - * removeAll, retainAll, and clear - * operations. It does not support the add or - * addAll operations. The view's iterator is a + * {@code Iterator.remove}, {@code Collection.remove}, + * {@code removeAll}, {@code retainAll}, and {@code clear} + * operations. It does not support the {@code add} or + * {@code addAll} operations. The view's {@code iterator} is a * "weakly consistent" iterator that will never throw {@link * java.util.ConcurrentModificationException}, and guarantees to * traverse elements as they existed upon construction of the * iterator, and may (but is not guaranteed to) reflect any * modifications subsequent to construction. The - * Map.Entry elements returned by - * iterator.next() do not support the - * setValue operation. + * {@code Map.Entry} elements returned by + * {@code iterator.next()} do not support the + * {@code setValue} operation. * - * @return a collection view of the mappings contained in this map. + * @return a collection view of the mappings contained in this map */ public Set> entrySet() { EntrySet es = entrySet; @@ -2015,24 +2015,24 @@ public class ConcurrentSkipListMap /** * Returns a collection view of the mappings contained in this * map, in descending order. Each element in the returned - * collection is a Map.Entry. The collection is backed + * collection is a {@code Map.Entry}. The collection is backed * by the map, so changes to the map are reflected in the * collection, and vice-versa. The collection supports element * removal, which removes the corresponding mapping from the map, - * via the Iterator.remove, Collection.remove, - * removeAll, retainAll, and clear - * operations. It does not support the add or - * addAll operations. The view's iterator is a + * via the {@code Iterator.remove}, {@code Collection.remove}, + * {@code removeAll}, {@code retainAll}, and {@code clear} + * operations. It does not support the {@code add} or + * {@code addAll} operations. The view's {@code iterator} is a * "weakly consistent" iterator that will never throw {@link * java.util.ConcurrentModificationException}, and guarantees to * traverse elements as they existed upon construction of the * iterator, and may (but is not guaranteed to) reflect any * modifications subsequent to construction. The - * Map.Entry elements returned by - * iterator.next() do not support the - * setValue operation. + * {@code Map.Entry} elements returned by + * {@code iterator.next()} do not support the + * {@code setValue} operation. * - * @return a collection view of the mappings contained in this map. + * @return a collection view of the mappings contained in this map */ public Set> descendingEntrySet() { DescendingEntrySet es = descendingEntrySet; @@ -2043,17 +2043,17 @@ public class ConcurrentSkipListMap /** * Compares the specified object with this map for equality. - * Returns true if the given object is also a map and the + * Returns {@code true} if the given object is also a map and the * two maps represent the same mappings. More formally, two maps - * t1 and t2 represent the same mappings if - * t1.keySet().equals(t2.keySet()) and for every key - * k in t1.keySet(), (t1.get(k)==null ? - * t2.get(k)==null : t1.get(k).equals(t2.get(k))) . This + * {@code t1} and {@code t2} represent the same mappings if + * {@code t1.keySet().equals(t2.keySet())} and for every key + * {@code k} in {@code t1.keySet()}, {@code (t1.get(k)==null ? + * t2.get(k)==null : t1.get(k).equals(t2.get(k))) }. This * operation may return misleading results if either map is * concurrently modified during execution of this method. * - * @param o object to be compared for equality with this map. - * @return true if the specified object is equal to this map. + * @param o object to be compared for equality with this map + * @return {@code true} if the specified object is equal to this map */ public boolean equals(Object o) { if (o == this) @@ -2094,19 +2094,19 @@ 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. - * @param value value to be associated with the specified key. - * @return previous value associated with specified key, or null - * if there was no mapping for key. + * @param key key with which the specified value is to be associated + * @param value value to be associated with the specified key + * @return previous value associated with specified key, or {@code null} + * if there was no mapping for key * * @throws ClassCastException if the key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if the key or value are null. + * currently in the map + * @throws NullPointerException if the key or value are {@code null} */ public V putIfAbsent(K key, V value) { if (value == null) @@ -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)) {
@@ -2124,12 +2124,12 @@ public class ConcurrentSkipListMap
      * } else return false;
      *
* except that the action is performed atomically. - * @param key key with which the specified value is associated. - * @param value value associated with the specified key. + * @param key key with which the specified value is associated + * @param value value associated with the specified key * @return true if the value was removed, false otherwise * @throws ClassCastException if the key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if the key or value are null. + * currently in the map + * @throws NullPointerException if the key or value are {@code null} */ public boolean remove(Object key, Object value) { if (value == null) @@ -2138,7 +2138,7 @@ public class ConcurrentSkipListMap } /** - * Replace entry for key only if currently mapped to given value. + * Replaces entry for key only if currently mapped to given value. * Acts as * 
      *  if ((map.containsKey(key) && map.get(key).equals(oldValue)) {
@@ -2147,14 +2147,14 @@ public class ConcurrentSkipListMap
      * } else return false;
      *
* except that the action is performed atomically. - * @param key key with which the specified value is associated. - * @param oldValue value expected to be associated with the specified key. - * @param newValue value to be associated with the specified key. + * @param key key with which the specified value is associated + * @param oldValue value expected to be associated with the specified key + * @param newValue value to be associated with the specified key * @return true if the value was replaced * @throws ClassCastException if the key cannot be compared with the keys - * currently in the map. + * currently in the map * @throws NullPointerException if key, oldValue or newValue are - * null. + * {@code null} */ public boolean replace(K key, V oldValue, V newValue) { if (oldValue == null || newValue == null) @@ -2175,7 +2175,7 @@ public class ConcurrentSkipListMap } /** - * Replace entry for key only if currently mapped to some value. + * Replaces entry for key only if currently mapped to some value. * Acts as * 
      *  if ((map.containsKey(key)) {
@@ -2183,13 +2183,13 @@ public class ConcurrentSkipListMap
      * } else return null;
      *
* except that the action is performed atomically. - * @param key key with which the specified value is associated. - * @param value value to be associated with the specified key. - * @return previous value associated with specified key, or null - * if there was no mapping for key. + * @param key key with which the specified value is associated + * @param value value to be associated with the specified key + * @return previous value associated with specified key, or {@code null} + * if there was no mapping for key * @throws ClassCastException if the key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if the key or value are null. + * currently in the map + * @throws NullPointerException if the key or value are {@code null} */ public V replace(K key, V value) { if (value == null) @@ -2208,11 +2208,11 @@ public class ConcurrentSkipListMap /* ------ SortedMap API methods ------ */ /** - * Returns the comparator used to order this map, or null + * Returns the comparator used to order this map, or {@code null} * if this map uses its keys' natural order. * * @return the comparator associated with this map, or - * null if it uses its keys' natural sort method. + * {@code null} if it uses its keys' natural sort method */ public Comparator comparator() { return comparator; @@ -2221,8 +2221,8 @@ public class ConcurrentSkipListMap /** * Returns the first (lowest) key currently in this map. * - * @return the first (lowest) key currently in this map. - * @throws NoSuchElementException Map is empty. + * @return the first (lowest) key currently in this map + * @throws NoSuchElementException Map is empty */ public K firstKey() { Node n = findFirst(); @@ -2234,8 +2234,8 @@ public class ConcurrentSkipListMap /** * Returns the last (highest) key currently in this map. * - * @return the last (highest) key currently in this map. - * @throws NoSuchElementException Map is empty. + * @return the last (highest) key currently in this map + * @throws NoSuchElementException Map is empty */ public K lastKey() { Node n = findLast(); @@ -2246,24 +2246,24 @@ public class ConcurrentSkipListMap /** * Returns a view of the portion of this map whose keys range from - * fromKey, inclusive, to toKey, exclusive. (If - * fromKey and toKey are equal, the returned sorted map + * {@code fromKey}, inclusive, to {@code toKey}, exclusive. (If + * {@code fromKey} and {@code 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. + * @param fromKey low endpoint (inclusive) of the subMap + * @param toKey high endpoint (exclusive) of the subMap * * @return a view of the portion of this map whose keys range from - * fromKey, inclusive, to toKey, exclusive. + * {@code fromKey}, inclusive, to {@code toKey}, exclusive * - * @throws ClassCastException if fromKey and toKey + * @throws ClassCastException if {@code fromKey} and {@code toKey} * cannot be compared to one another using this map's comparator - * (or, if the map has no comparator, using natural ordering). - * @throws IllegalArgumentException if fromKey is greater than - * toKey. - * @throws NullPointerException if fromKey or toKey is - * null. + * (or, if the map has no comparator, using natural ordering) + * @throws IllegalArgumentException if {@code fromKey} is greater than + * {@code toKey} + * @throws NullPointerException if {@code fromKey} or {@code toKey} is + * {@code null} */ public ConcurrentNavigableMap subMap(K fromKey, K toKey) { if (fromKey == null || toKey == null) @@ -2273,17 +2273,17 @@ public class ConcurrentSkipListMap /** * Returns a view of the portion of this map whose keys are - * strictly less than toKey. The returned sorted map is + * strictly less than {@code toKey}. 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 toKey high endpoint (exclusive) of the headMap. + * @param toKey high endpoint (exclusive) of the headMap * @return a view of the portion of this map whose keys are - * strictly less than toKey. + * strictly less than {@code toKey} * - * @throws ClassCastException if toKey is not compatible + * @throws ClassCastException if {@code toKey} is not compatible * with this map's comparator (or, if the map has no comparator, - * if toKey does not implement Comparable). - * @throws NullPointerException if toKey is null. + * if {@code toKey} does not implement {@code Comparable}) + * @throws NullPointerException if {@code toKey} is {@code null} */ public ConcurrentNavigableMap headMap(K toKey) { if (toKey == null) @@ -2293,19 +2293,19 @@ public class ConcurrentSkipListMap /** * Returns a view of the portion of this map whose keys are - * greater than or equal to fromKey. The returned sorted + * greater than or equal to {@code fromKey}. 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 tailMap. + * @param fromKey low endpoint (inclusive) of the tailMap * @return a view of the portion of this map whose keys are - * greater than or equal to fromKey. - * @throws ClassCastException if fromKey is not + * greater than or equal to {@code fromKey} + * @throws ClassCastException if {@code fromKey} is not * compatible with this map's comparator (or, if the map has no - * comparator, if fromKey does not implement - * Comparable). - * @throws NullPointerException if fromKey is null. + * comparator, if {@code fromKey} does not implement + * {@code Comparable}) + * @throws NullPointerException if {@code fromKey} is {@code null} */ - public ConcurrentNavigableMap tailMap(K fromKey) { + public ConcurrentNavigableMap tailMap(K fromKey) { if (fromKey == null) throw new NullPointerException(); return new ConcurrentSkipListSubMap(this, fromKey, null); @@ -2315,16 +2315,16 @@ public class ConcurrentSkipListMap /** * Returns a key-value mapping associated with the least key - * greater than or equal to the given key, or null if + * greater than or equal to the given key, or {@code null} if * there is no such entry. The returned entry does not - * support the Entry.setValue method. + * support the {@code Entry.setValue} method. * - * @param key the key. + * @param key the key * @return an Entry associated with ceiling of given key, or - * null if there is no such Entry. + * {@code null} if there is no such Entry * @throws ClassCastException if key cannot be compared with the - * keys currently in the map. - * @throws NullPointerException if key is null. + * keys currently in the map + * @throws NullPointerException if key is {@code null} */ public Map.Entry ceilingEntry(K key) { return getNear(key, GT|EQ); @@ -2332,14 +2332,14 @@ public class ConcurrentSkipListMap /** * Returns least key greater than or equal to the given key, or - * null if there is no such key. + * {@code null} if there is no such key. * - * @param key the key. - * @return the ceiling key, or null - * if there is no such key. + * @param key the key + * @return the ceiling key, or {@code null} + * if there is no such key * @throws ClassCastException if key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if key is null. + * currently in the map + * @throws NullPointerException if key is {@code null} */ public K ceilingKey(K key) { Node n = findNear(key, GT|EQ); @@ -2348,16 +2348,16 @@ public class ConcurrentSkipListMap /** * Returns a key-value mapping associated with the greatest - * key strictly less than the given key, or null if there is no + * key strictly less than the given key, or {@code null} if there is no * such entry. The returned entry does not support - * the Entry.setValue method. + * the {@code Entry.setValue} method. * - * @param key the key. + * @param key the key * @return an Entry with greatest key less than the given - * key, or null if there is no such Entry. + * key, or {@code null} if there is no such Entry * @throws ClassCastException if key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if key is null. + * currently in the map + * @throws NullPointerException if key is {@code null} */ public Map.Entry lowerEntry(K key) { return getNear(key, LT); @@ -2365,14 +2365,14 @@ public class ConcurrentSkipListMap /** * Returns the greatest key strictly less than the given key, or - * null if there is no such key. + * {@code null} if there is no such key. * - * @param key the key. + * @param key the key * @return the greatest key less than the given - * key, or null if there is no such key. + * key, or {@code null} if there is no such key * @throws ClassCastException if key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if key is null. + * currently in the map + * @throws NullPointerException if key is {@code null} */ public K lowerKey(K key) { Node n = findNear(key, LT); @@ -2381,16 +2381,16 @@ public class ConcurrentSkipListMap /** * Returns a key-value mapping associated with the greatest key - * less than or equal to the given key, or null if there + * less than or equal to the given key, or {@code null} if there * is no such entry. The returned entry does not support - * the Entry.setValue method. + * the {@code Entry.setValue} method. * - * @param key the key. - * @return an Entry associated with floor of given key, or null - * if there is no such Entry. + * @param key the key + * @return an Entry associated with floor of given key, or {@code null} + * if there is no such Entry * @throws ClassCastException if key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if key is null. + * currently in the map + * @throws NullPointerException if key is {@code null} */ public Map.Entry floorEntry(K key) { return getNear(key, LT|EQ); @@ -2398,15 +2398,15 @@ public class ConcurrentSkipListMap /** * Returns the greatest key - * less than or equal to the given key, or null if there + * less than or equal to the given key, or {@code null} if there * is no such key. * - * @param key the key. - * @return the floor of given key, or null if there is no - * such key. + * @param key the key + * @return the floor of given key, or {@code null} if there is no + * such key * @throws ClassCastException if key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if key is null. + * currently in the map + * @throws NullPointerException if key is {@code null} */ public K floorKey(K key) { Node n = findNear(key, LT|EQ); @@ -2415,16 +2415,16 @@ public class ConcurrentSkipListMap /** * Returns a key-value mapping associated with the least key - * strictly greater than the given key, or null if there + * strictly greater than the given key, or {@code null} if there * is no such entry. The returned entry does not support - * the Entry.setValue method. + * the {@code Entry.setValue} method. * - * @param key the key. + * @param key the key * @return an Entry with least key greater than the given key, or - * null if there is no such Entry. + * {@code null} if there is no such Entry * @throws ClassCastException if key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if key is null. + * currently in the map + * @throws NullPointerException if key is {@code null} */ public Map.Entry higherEntry(K key) { return getNear(key, GT); @@ -2432,14 +2432,14 @@ public class ConcurrentSkipListMap /** * Returns the least key strictly greater than the given key, or - * null if there is no such key. + * {@code null} if there is no such key. * - * @param key the key. + * @param key the key * @return the least key greater than the given key, or - * null if there is no such key. + * {@code null} if there is no such key * @throws ClassCastException if key cannot be compared with the keys - * currently in the map. - * @throws NullPointerException if key is null. + * currently in the map + * @throws NullPointerException if key is {@code null} */ public K higherKey(K key) { Node n = findNear(key, GT); @@ -2448,12 +2448,12 @@ public class ConcurrentSkipListMap /** * Returns a key-value mapping associated with the least - * key in this map, or null if the map is empty. + * key in this map, or {@code null} if the map is empty. * The returned entry does not support - * the Entry.setValue method. + * the {@code Entry.setValue} method. * - * @return an Entry with least key, or null - * if the map is empty. + * @return an Entry with least key, or {@code null} + * if the map is empty */ public Map.Entry firstEntry() { for (;;) { @@ -2468,12 +2468,12 @@ public class ConcurrentSkipListMap /** * Returns a key-value mapping associated with the greatest - * key in this map, or null if the map is empty. + * key in this map, or {@code null} if the map is empty. * The returned entry does not support - * the Entry.setValue method. + * the {@code Entry.setValue} method. * - * @return an Entry with greatest key, or null - * if the map is empty. + * @return an Entry with greatest key, or {@code null} + * if the map is empty */ public Map.Entry lastEntry() { for (;;) { @@ -2488,12 +2488,12 @@ public class ConcurrentSkipListMap /** * Removes and returns a key-value mapping associated with - * the least key in this map, or null if the map is empty. + * the least key in this map, or {@code null} if the map is empty. * The returned entry does not support - * the Entry.setValue method. + * the {@code Entry.setValue} method. * - * @return the removed first entry of this map, or null - * if the map is empty. + * @return the removed first entry of this map, or {@code null} + * if the map is empty */ public Map.Entry pollFirstEntry() { return (SnapshotEntry)doRemoveFirst(false); @@ -2501,12 +2501,12 @@ public class ConcurrentSkipListMap /** * Removes and returns a key-value mapping associated with - * the greatest key in this map, or null if the map is empty. + * the greatest key in this map, or {@code null} if the map is empty. * The returned entry does not support - * the Entry.setValue method. + * the {@code Entry.setValue} method. * - * @return the removed last entry of this map, or null - * if the map is empty. + * @return the removed last entry of this map, or {@code null} + * if the map is empty */ public Map.Entry pollLastEntry() { return (SnapshotEntry)doRemoveLast(false); @@ -2548,8 +2548,8 @@ public class ConcurrentSkipListMap /** * initialize ascending iterator starting at given least key, - * or first node if least is null, but not greater or - * equal to fence, or end if fence is null. + * or first node if least is {@code null}, but not greater or + * equal to fence, or end if fence is {@code null}. */ final void initAscending(K least, K fence) { for (;;) { @@ -2616,8 +2616,8 @@ public class ConcurrentSkipListMap /** * initialize descending iterator starting at key less * than or equal to given fence key, or - * last node if fence is null, but not less than - * least, or beginning if lest is null. + * last node if fence is {@code null}, but not less than + * least, or beginning if lest is {@code null}. */ final void initDescending(K least, K fence) { for (;;) { @@ -2842,7 +2842,7 @@ public class ConcurrentSkipListMap } final class DescendingEntryIterator extends EntryIter - implements Iterator> { + implements Iterator> { DescendingEntryIterator() { initDescending(); } @@ -2854,7 +2854,7 @@ public class ConcurrentSkipListMap } final class DescendingSubMapEntryIterator extends EntryIter - implements Iterator> { + implements Iterator> { final K least; DescendingSubMapEntryIterator(K least, K fence) { initDescending(least, fence); @@ -3025,8 +3025,8 @@ public class ConcurrentSkipListMap * underlying maps, differing in that mappings outside their range are * ignored, and attempts to add mappings outside their ranges result * in {@link IllegalArgumentException}. Instances of this class are - * constructed only using the subMap, headMap, and - * tailMap methods of their underlying maps. + * constructed only using the {@code subMap}, {@code headMap}, and + * {@code tailMap} methods of their underlying maps. */ static class ConcurrentSkipListSubMap extends AbstractMap implements ConcurrentNavigableMap, java.io.Serializable { @@ -3048,8 +3048,8 @@ 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 + * @param least inclusive least value, or {@code null} if from start + * @param fence exclusive upper bound, or {@code null} if to end * @throws IllegalArgumentException if least and fence non-null * and least greater than fence */ @@ -3095,7 +3095,7 @@ public class ConcurrentSkipListMap } /** - * Returns underlying map. Needed by ConcurrentSkipListSet + * Returns underlying map. Needed by ConcurrentSkipListSet. * @return the backing map */ ConcurrentSkipListMap getMap() { @@ -3103,16 +3103,16 @@ public class ConcurrentSkipListMap } /** - * Returns least key. Needed by ConcurrentSkipListSet - * @return least key or null if from start + * Returns least key. Needed by ConcurrentSkipListSet. + * @return least key, or {@code null} if from start */ K getLeast() { return least; } /** - * Returns fence key. Needed by ConcurrentSkipListSet - * @return fence key or null of to end + * Returns fence key. Needed by ConcurrentSkipListSet. + * @return fence key, or {@code null} if to end */ K getFence() { return fence; @@ -3241,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)) @@ -3253,43 +3253,43 @@ public class ConcurrentSkipListMap public Map.Entry ceilingEntry(K key) { return (SnapshotEntry) - m.getNear(key, m.GT|m.EQ, least, fence, false); + m.getNear(key, GT|EQ, least, fence, false); } public K ceilingKey(K key) { return (K) - m.getNear(key, m.GT|m.EQ, least, fence, true); + m.getNear(key, GT|EQ, least, fence, true); } public Map.Entry lowerEntry(K key) { return (SnapshotEntry) - m.getNear(key, m.LT, least, fence, false); + m.getNear(key, LT, least, fence, false); } public K lowerKey(K key) { return (K) - m.getNear(key, m.LT, least, fence, true); + m.getNear(key, LT, least, fence, true); } public Map.Entry floorEntry(K key) { return (SnapshotEntry) - m.getNear(key, m.LT|m.EQ, least, fence, false); + m.getNear(key, LT|EQ, least, fence, false); } public K floorKey(K key) { return (K) - m.getNear(key, m.LT|m.EQ, least, fence, true); + m.getNear(key, LT|EQ, least, fence, true); } public Map.Entry higherEntry(K key) { return (SnapshotEntry) - m.getNear(key, m.GT, least, fence, false); + m.getNear(key, GT, least, fence, false); } public K higherKey(K key) { return (K) - m.getNear(key, m.GT, least, fence, true); + m.getNear(key, GT, least, fence, true); } public Map.Entry firstEntry() {