| 25 |
|
* <li> {@linkplain SoftReference Soft}, {@linkplain |
| 26 |
|
* WeakReference weak} or strong (regular) keys and values. |
| 27 |
|
* |
| 28 |
< |
* <li> User-definable <code>MappingFunctions</code> that may be |
| 28 |
> |
* <li> User-definable {@code MappingFunctions} that may be |
| 29 |
|
* used in method {@link |
| 30 |
|
* CustomConcurrentHashMap#computeIfAbsent} to atomically |
| 31 |
|
* establish a computed value, along with |
| 32 |
< |
* <code>RemappingFunctions</code> that can be used in method |
| 32 |
> |
* {@code RemappingFunctions} that can be used in method |
| 33 |
|
* {@link CustomConcurrentHashMap#compute} to atomically |
| 34 |
|
* replace values. |
| 35 |
|
* |
| 36 |
< |
* <li>Factory methods returning specialized forms for <tt>int</tt> |
| 36 |
> |
* <li>Factory methods returning specialized forms for {@code int} |
| 37 |
|
* keys and/or values, that may be more space-efficient |
| 38 |
|
* |
| 39 |
|
* </ul> |
| 72 |
|
* |
| 73 |
|
* <p>This class also includes nested class {@link KeySet} |
| 74 |
|
* that provides space-efficient Set views of maps, also supporting |
| 75 |
< |
* method <code>intern</code>, which may be of use in canonicalizing |
| 75 |
> |
* method {@code intern}, which may be of use in canonicalizing |
| 76 |
|
* elements. |
| 77 |
|
* |
| 78 |
|
* <p>When used with (Weak or Soft) Reference keys and/or values, |
| 79 |
< |
* elements that have asynchronously become <code>null</code> are |
| 79 |
> |
* elements that have asynchronously become {@code null} are |
| 80 |
|
* treated as absent from the map and (eventually) removed from maps |
| 81 |
|
* via a background thread common across all maps. Because of the |
| 82 |
|
* potential for asynchronous clearing of References, methods such as |
| 83 |
< |
* <code>containsValue</code> have weaker guarantees than you might |
| 83 |
> |
* {@code containsValue} have weaker guarantees than you might |
| 84 |
|
* expect even in the absence of other explicitly concurrent |
| 85 |
< |
* operations. For example <code>containsValue(value)</code> may |
| 86 |
< |
* return true even if <code>value</code> is no longer available upon |
| 85 |
> |
* operations. For example {@code containsValue(value)} may |
| 86 |
> |
* return true even if {@code value} is no longer available upon |
| 87 |
|
* return from the method. |
| 88 |
|
* |
| 89 |
|
* <p>When Equivalences other than equality are used, the returned |
| 90 |
< |
* collections may violate the specifications of <tt>Map</tt> and/or |
| 91 |
< |
* <tt>Set</tt> interfaces, which mandate the use of the |
| 92 |
< |
* <tt>equals</tt> method when comparing objects. The methods of this |
| 90 |
> |
* collections may violate the specifications of {@code Map} and/or |
| 91 |
> |
* {@code Set} interfaces, which mandate the use of the |
| 92 |
> |
* {@code equals} method when comparing objects. The methods of this |
| 93 |
|
* class otherwise have properties similar to those of {@link |
| 94 |
|
* java.util.ConcurrentHashMap} under its default settings. To |
| 95 |
|
* adaptively maintain semantics and performance under varying |
| 165 |
|
* An object performing equality comparisons, along with a hash |
| 166 |
|
* function consistent with this comparison. The type signatures |
| 167 |
|
* of the methods of this interface reflect those of {@link |
| 168 |
< |
* java.util.Map}: While only elements of <code>K</code> may be |
| 169 |
< |
* entered into a Map, any <code>Object</code> may be tested for |
| 168 |
> |
* java.util.Map}: While only elements of {@code K} may be |
| 169 |
> |
* entered into a Map, any {@code Object} may be tested for |
| 170 |
|
* membership. Note that the performance of hash maps is heavily |
| 171 |
|
* dependent on the quality of hash functions. |
| 172 |
|
*/ |
| 224 |
|
|
| 225 |
|
/** |
| 226 |
|
* A function computing a mapping from the given key to a value, |
| 227 |
< |
* or <code>null</code> if there is no mapping. |
| 227 |
> |
* or {@code null} if there is no mapping. |
| 228 |
|
*/ |
| 229 |
|
public static interface MappingFunction<K, V> { |
| 230 |
|
/** |
| 244 |
|
|
| 245 |
|
/** |
| 246 |
|
* A function computing a new mapping from the given key and its |
| 247 |
< |
* current value to a new value, or <code>null</code> if there is |
| 247 |
> |
* current value to a new value, or {@code null} if there is |
| 248 |
|
* no mapping |
| 249 |
|
*/ |
| 250 |
|
public static interface RemappingFunction<K, V> { |
| 678 |
|
} |
| 679 |
|
|
| 680 |
|
/** |
| 681 |
< |
* Returns <tt>true</tt> if this map contains a key equivalent to |
| 681 |
> |
* Returns {@code true} if this map contains a key equivalent to |
| 682 |
|
* the given key with respect to this map's key Equivalence. |
| 683 |
|
* |
| 684 |
|
* @param key possible key |
| 685 |
< |
* @return <tt>true</tt> if this map contains the specified key |
| 685 |
> |
* @return {@code true} if this map contains the specified key |
| 686 |
|
* @throws NullPointerException if the specified key is null |
| 687 |
|
*/ |
| 688 |
|
public boolean containsKey(Object key) { |
| 700 |
|
* if no such mapping exists. |
| 701 |
|
* |
| 702 |
|
* @param key possible key |
| 703 |
< |
* @return the value associated with the key or <tt>null</tt> if |
| 703 |
> |
* @return the value associated with the key or {@code null} if |
| 704 |
|
* there is no mapping. |
| 705 |
|
* @throws NullPointerException if the specified key is null |
| 706 |
|
*/ |
| 752 |
|
* |
| 753 |
|
* @param key key with which the specified value is to be associated |
| 754 |
|
* @param value value to be associated with the specified key |
| 755 |
< |
* @return the previous value associated with <tt>key</tt>, or |
| 756 |
< |
* <tt>null</tt> if there was no mapping for <tt>key</tt> |
| 755 |
> |
* @return the previous value associated with {@code key}, or |
| 756 |
> |
* {@code null} if there was no mapping for {@code key} |
| 757 |
|
* @throws NullPointerException if the specified key or value is null |
| 758 |
|
*/ |
| 759 |
|
public V put(K key, V value) { |
| 764 |
|
* {@inheritDoc} |
| 765 |
|
* |
| 766 |
|
* @return the previous value associated with the specified key, |
| 767 |
< |
* or <tt>null</tt> if there was no mapping for the key |
| 767 |
> |
* or {@code null} if there was no mapping for the key |
| 768 |
|
* @throws NullPointerException if the specified key or value is null |
| 769 |
|
*/ |
| 770 |
|
public V putIfAbsent(K key, V value) { |
| 813 |
|
* {@inheritDoc} |
| 814 |
|
* |
| 815 |
|
* @return the previous value associated with the specified key, |
| 816 |
< |
* or <tt>null</tt> if there was no mapping for the key |
| 816 |
> |
* or {@code null} if there was no mapping for the key |
| 817 |
|
* @throws NullPointerException if the specified key or value is null |
| 818 |
|
*/ |
| 819 |
|
public boolean replace(K key, V oldValue, V newValue) { |
| 845 |
|
* Removes the mapping for the specified key. |
| 846 |
|
* |
| 847 |
|
* @param key the key to remove |
| 848 |
< |
* @return the previous value associated with <tt>key</tt>, or |
| 849 |
< |
* <tt>null</tt> if there was no mapping for <tt>key</tt> |
| 848 |
> |
* @return the previous value associated with {@code key}, or |
| 849 |
> |
* {@code null} if there was no mapping for {@code key} |
| 850 |
|
* @throws NullPointerException if the specified key is null |
| 851 |
|
*/ |
| 852 |
|
public V remove(Object key) { |
| 979 |
|
} |
| 980 |
|
|
| 981 |
|
/** |
| 982 |
< |
* Returns <tt>true</tt> if this map contains no key-value mappings. |
| 982 |
> |
* Returns {@code true} if this map contains no key-value mappings. |
| 983 |
|
* |
| 984 |
< |
* @return <tt>true</tt> if this map contains no key-value mappings |
| 984 |
> |
* @return {@code true} if this map contains no key-value mappings |
| 985 |
|
*/ |
| 986 |
|
public final boolean isEmpty() { |
| 987 |
|
final Segment[] segs = this.segments; |
| 997 |
|
|
| 998 |
|
/** |
| 999 |
|
* Returns the number of key-value mappings in this map. If the |
| 1000 |
< |
* map contains more than <tt>Integer.MAX_VALUE</tt> elements, returns |
| 1001 |
< |
* <tt>Integer.MAX_VALUE</tt>. |
| 1000 |
> |
* map contains more than {@code Integer.MAX_VALUE} elements, returns |
| 1001 |
> |
* {@code Integer.MAX_VALUE}. |
| 1002 |
|
* |
| 1003 |
|
* @return the number of key-value mappings in this map |
| 1004 |
|
*/ |
| 1014 |
|
} |
| 1015 |
|
|
| 1016 |
|
/** |
| 1017 |
< |
* Returns <tt>true</tt> if this map maps one or more keys to a |
| 1017 |
> |
* Returns {@code true} if this map maps one or more keys to a |
| 1018 |
|
* value equivalent to the given value with respect to this map's |
| 1019 |
|
* value Equivalence. Note: This method requires a full internal |
| 1020 |
|
* traversal of the hash table, and so is much slower than method |
| 1021 |
< |
* <tt>containsKey</tt>. |
| 1021 |
> |
* {@code containsKey}. |
| 1022 |
|
* |
| 1023 |
|
* @param value value whose presence in this map is to be tested |
| 1024 |
< |
* @return <tt>true</tt> if this map maps one or more keys to the |
| 1024 |
> |
* @return {@code true} if this map maps one or more keys to the |
| 1025 |
|
* specified value |
| 1026 |
|
* @throws NullPointerException if the specified value is null |
| 1027 |
|
*/ |
| 1091 |
|
* @param key key with which the specified value is to be associated |
| 1092 |
|
* @param mappingFunction the function to compute a value |
| 1093 |
|
* @return the current (existing or computed) value associated with |
| 1094 |
< |
* the specified key, or <tt>null</tt> if the computation |
| 1095 |
< |
* returned <tt>null</tt>. |
| 1094 |
> |
* the specified key, or {@code null} if the computation |
| 1095 |
> |
* returned {@code null}. |
| 1096 |
|
* @throws NullPointerException if the specified key or mappingFunction |
| 1097 |
|
* is null, |
| 1098 |
|
* @throws RuntimeException or Error if the mappingFunction does so, |
| 1165 |
|
* @param key key with which the specified value is to be associated |
| 1166 |
|
* @param remappingFunction the function to compute a value |
| 1167 |
|
* @return the updated value or |
| 1168 |
< |
* <tt>null</tt> if the computation returned <tt>null</tt> |
| 1168 |
> |
* {@code null} if the computation returned {@code null} |
| 1169 |
|
* @throws NullPointerException if the specified key or remappingFunction |
| 1170 |
|
* is null, |
| 1171 |
|
* @throws RuntimeException or Error if the remappingFunction does so, |
| 1433 |
|
* The set is backed by the map, so changes to the map are |
| 1434 |
|
* reflected in the set, and vice-versa. The set supports element |
| 1435 |
|
* removal, which removes the corresponding mapping from this map, |
| 1436 |
< |
* via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>, |
| 1437 |
< |
* <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt> |
| 1438 |
< |
* operations. It does not support the <tt>add</tt> or |
| 1439 |
< |
* <tt>addAll</tt> operations. |
| 1436 |
> |
* via the {@code Iterator.remove}, {@code Set.remove}, |
| 1437 |
> |
* {@code removeAll}, {@code retainAll}, and {@code clear} |
| 1438 |
> |
* operations. It does not support the {@code add} or |
| 1439 |
> |
* {@code addAll} operations. |
| 1440 |
|
* |
| 1441 |
< |
* <p>The view's <tt>iterator</tt> is a "weakly consistent" iterator |
| 1441 |
> |
* <p>The view's {@code iterator} is a "weakly consistent" iterator |
| 1442 |
|
* that will never throw {@link ConcurrentModificationException}, |
| 1443 |
|
* and guarantees to traverse elements as they existed upon |
| 1444 |
|
* construction of the iterator, and may (but is not guaranteed to) |
| 1454 |
|
* The collection is backed by the map, so changes to the map are |
| 1455 |
|
* reflected in the collection, and vice-versa. The collection |
| 1456 |
|
* supports element removal, which removes the corresponding |
| 1457 |
< |
* mapping from this map, via the <tt>Iterator.remove</tt>, |
| 1458 |
< |
* <tt>Collection.remove</tt>, <tt>removeAll</tt>, |
| 1459 |
< |
* <tt>retainAll</tt>, and <tt>clear</tt> operations. It does not |
| 1460 |
< |
* support the <tt>add</tt> or <tt>addAll</tt> operations. |
| 1457 |
> |
* mapping from this map, via the {@code Iterator.remove}, |
| 1458 |
> |
* {@code Collection.remove}, {@code removeAll}, |
| 1459 |
> |
* {@code retainAll}, and {@code clear} operations. It does not |
| 1460 |
> |
* support the {@code add} or {@code addAll} operations. |
| 1461 |
|
* |
| 1462 |
< |
* <p>The view's <tt>iterator</tt> is a "weakly consistent" iterator |
| 1462 |
> |
* <p>The view's {@code iterator} is a "weakly consistent" iterator |
| 1463 |
|
* that will never throw {@link ConcurrentModificationException}, |
| 1464 |
|
* and guarantees to traverse elements as they existed upon |
| 1465 |
|
* construction of the iterator, and may (but is not guaranteed to) |
| 1475 |
|
* The set is backed by the map, so changes to the map are |
| 1476 |
|
* reflected in the set, and vice-versa. The set supports element |
| 1477 |
|
* removal, which removes the corresponding mapping from the map, |
| 1478 |
< |
* via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>, |
| 1479 |
< |
* <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt> |
| 1480 |
< |
* operations. It does not support the <tt>add</tt> or |
| 1481 |
< |
* <tt>addAll</tt> operations. |
| 1478 |
> |
* via the {@code Iterator.remove}, {@code Set.remove}, |
| 1479 |
> |
* {@code removeAll}, {@code retainAll}, and {@code clear} |
| 1480 |
> |
* operations. It does not support the {@code add} or |
| 1481 |
> |
* {@code addAll} operations. |
| 1482 |
|
* |
| 1483 |
< |
* <p>The view's <tt>iterator</tt> is a "weakly consistent" iterator |
| 1483 |
> |
* <p>The view's {@code iterator} is a "weakly consistent" iterator |
| 1484 |
|
* that will never throw {@link ConcurrentModificationException}, |
| 1485 |
|
* and guarantees to traverse elements as they existed upon |
| 1486 |
|
* construction of the iterator, and may (but is not guaranteed to) |
| 1495 |
|
|
| 1496 |
|
/** |
| 1497 |
|
* Compares the specified object with this map for equality. |
| 1498 |
< |
* Returns <tt>true</tt> if the given object is also a map of the |
| 1498 |
> |
* Returns {@code true} if the given object is also a map of the |
| 1499 |
|
* same size, holding keys that are equal using this Map's key |
| 1500 |
|
* Equivalence, and which map to values that are equal according |
| 1501 |
|
* to this Map's value equivalence. |
| 1502 |
|
* |
| 1503 |
|
* @param o object to be compared for equality with this map |
| 1504 |
< |
* @return <tt>true</tt> if the specified object is equal to this map |
| 1504 |
> |
* @return {@code true} if the specified object is equal to this map |
| 1505 |
|
*/ |
| 1506 |
|
public boolean equals(Object o) { |
| 1507 |
|
if (o == this) |
| 1538 |
|
|
| 1539 |
|
/** |
| 1540 |
|
* Returns the sum of the hash codes of each entry in this map's |
| 1541 |
< |
* <tt>entrySet()</tt> view, which in turn are the hash codes |
| 1541 |
> |
* {@code entrySet()} view, which in turn are the hash codes |
| 1542 |
|
* computed using key and value Equivalences for this Map. |
| 1543 |
|
* @return the hash code |
| 1544 |
|
*/ |
| 1588 |
|
|
| 1589 |
|
/** |
| 1590 |
|
* A hash-based set with properties identical to those of |
| 1591 |
< |
* <code>Collections.newSetFromMap</code> applied to a |
| 1592 |
< |
* <code>CustomConcurrentHashMap</code>, but possibly more |
| 1591 |
> |
* {@code Collections.newSetFromMap} applied to a |
| 1592 |
> |
* {@code CustomConcurrentHashMap}, but possibly more |
| 1593 |
|
* space-efficient. The set does not permit null elements. The |
| 1594 |
|
* set is serializable; however, serializing a set that uses soft |
| 1595 |
|
* or weak references can give unpredictable results. |
| 1629 |
|
} |
| 1630 |
|
|
| 1631 |
|
/** |
| 1632 |
< |
* Returns <tt>true</tt> if this set contains an |
| 1632 |
> |
* Returns {@code true} if this set contains an |
| 1633 |
|
* element equivalent to the given element with respect |
| 1634 |
|
* to this set's Equivalence. |
| 1635 |
|
* @param o element whose presence in this set is to be tested |
| 1636 |
< |
* @return <tt>true</tt> if this set contains the specified element |
| 1636 |
> |
* @return {@code true} if this set contains the specified element |
| 1637 |
|
*/ |
| 1638 |
|
public boolean contains(Object o) { |
| 1639 |
|
return cchm.containsKey(o); |
| 1656 |
|
* respect to this set's Equivalence. |
| 1657 |
|
* |
| 1658 |
|
* @param e element to be added to this set |
| 1659 |
< |
* @return <tt>true</tt> if this set did not already contain |
| 1659 |
> |
* @return {@code true} if this set did not already contain |
| 1660 |
|
* the specified element |
| 1661 |
|
*/ |
| 1662 |
|
public boolean add(K e) { |
| 1668 |
|
* respect to this set's Equivalence, if one is present. |
| 1669 |
|
* |
| 1670 |
|
* @param o object to be removed from this set, if present |
| 1671 |
< |
* @return <tt>true</tt> if the set contained the specified element |
| 1671 |
> |
* @return {@code true} if the set contained the specified element |
| 1672 |
|
*/ |
| 1673 |
|
public boolean remove(Object o) { |
| 1674 |
|
return cchm.remove(o) != null; |
| 1675 |
|
} |
| 1676 |
|
|
| 1677 |
|
/** |
| 1678 |
< |
* Returns <tt>true</tt> if this set contains no elements. |
| 1678 |
> |
* Returns {@code true} if this set contains no elements. |
| 1679 |
|
* |
| 1680 |
< |
* @return <tt>true</tt> if this set contains no elements |
| 1680 |
> |
* @return {@code true} if this set contains no elements |
| 1681 |
|
*/ |
| 1682 |
|
public boolean isEmpty() { |
| 1683 |
|
return cchm.isEmpty(); |
