WeakIdentityMap (Lucene 7.5.0 API)

java.lang.Object
- org.apache.lucene.util.WeakIdentityMap<K,V>

```
public final class WeakIdentityMap<K,V>
extends Object
```
Implements a combination of WeakHashMap and IdentityHashMap. Useful for caches that need to key off of a == comparison instead of a .equals.
This class is not a general-purpose Map implementation! It intentionally violates Map's general contract, which mandates the use of the equals method when comparing objects. This class is designed for use only in the rare cases wherein reference-equality semantics are required.
This implementation was forked from Apache CXF but modified to not implement the Map interface and without any set views on it, as those are error-prone and inefficient, if not implemented carefully. The map only contains Iterator implementations on the values and not-GCed keys. Lucene's implementation also supports null keys, but those are never weak!
The map supports two modes of operation:
- reapOnRead = true: This behaves identical to a WeakHashMap where it also cleans up the reference queue on every read operation (get(Object), containsKey(Object), size(), valueIterator()), freeing map entries of already GCed keys.
- reapOnRead = false: This mode does not call reap() on every read operation. In this case, the reference queue is only cleaned up on write operations (like put(Object, Object)). This is ideal for maps with few entries where the keys are unlikely be garbage collected, but there are lots of get(Object) operations. The code can still call reap() to manually clean up the queue without doing a write operation.
NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clear()` Removes all of the mappings from this map.
`boolean`	`containsKey(Object key)` Returns `true` if this map contains a mapping for the specified key.
`V`	`get(Object key)` Returns the value to which the specified key is mapped.
`boolean`	`isEmpty()` Returns `true` if this map contains no key-value mappings.
`Iterator<K>`	`keyIterator()` Returns an iterator over all weak keys of this map.
`static <K,V> WeakIdentityMap<K,V>`	`newConcurrentHashMap()` Creates a new `WeakIdentityMap` based on a `ConcurrentHashMap`.
`static <K,V> WeakIdentityMap<K,V>`	`newConcurrentHashMap(boolean reapOnRead)` Creates a new `WeakIdentityMap` based on a `ConcurrentHashMap`.
`static <K,V> WeakIdentityMap<K,V>`	`newHashMap()` Creates a new `WeakIdentityMap` based on a non-synchronized `HashMap`.
`static <K,V> WeakIdentityMap<K,V>`	`newHashMap(boolean reapOnRead)` Creates a new `WeakIdentityMap` based on a non-synchronized `HashMap`.
`V`	`put(K key, V value)` Associates the specified value with the specified key in this map.
`void`	`reap()` This method manually cleans up the reference queue to remove all garbage collected key/value pairs from the map.
`V`	`remove(Object key)` Removes the mapping for a key from this weak hash map if it is present.
`int`	`size()` Returns the number of key-value mappings in this map.
`Iterator<V>`	`valueIterator()` Returns an iterator over all values of this map.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - newHashMap
```
public static <K,V> WeakIdentityMap<K,V> newHashMap()
```
    Creates a new WeakIdentityMap based on a non-synchronized HashMap. The map cleans up the reference queue on every read operation.
  - newHashMap
```
public static <K,V> WeakIdentityMap<K,V> newHashMap(boolean reapOnRead)
```
    Creates a new WeakIdentityMap based on a non-synchronized HashMap.
    
    Parameters:
    
    reapOnRead - controls if the map cleans up the reference queue on every read operation.
  - newConcurrentHashMap
```
public static <K,V> WeakIdentityMap<K,V> newConcurrentHashMap()
```
    Creates a new WeakIdentityMap based on a ConcurrentHashMap. The map cleans up the reference queue on every read operation.
  - newConcurrentHashMap
```
public static <K,V> WeakIdentityMap<K,V> newConcurrentHashMap(boolean reapOnRead)
```
    Creates a new WeakIdentityMap based on a ConcurrentHashMap.
    
    Parameters:
    
    reapOnRead - controls if the map cleans up the reference queue on every read operation.
  - clear
```
public void clear()
```
    Removes all of the mappings from this map.
  - containsKey
```
public boolean containsKey(Object key)
```
    Returns true if this map contains a mapping for the specified key.
  - get
```
public V get(Object key)
```
    Returns the value to which the specified key is mapped.
  - put
```
public V put(K key,
             V value)
```
    Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced.
  - isEmpty
```
public boolean isEmpty()
```
    Returns true if this map contains no key-value mappings.
  - remove
```
public V remove(Object key)
```
    Removes the mapping for a key from this weak hash map if it is present. Returns the value to which this map previously associated the key, or null if the map contained no mapping for the key. A return value of null does not necessarily indicate that the map contained.
  - size
```
public int size()
```
    Returns the number of key-value mappings in this map. This result is a snapshot, and may not reflect unprocessed entries that will be removed before next attempted access because they are no longer referenced.
  - keyIterator
```
public Iterator<K> keyIterator()
```
    Returns an iterator over all weak keys of this map. Keys already garbage collected will not be returned. This Iterator does not support removals.
  - valueIterator
```
public Iterator<V> valueIterator()
```
    Returns an iterator over all values of this map. This iterator may return values whose key is already garbage collected while iterator is consumed, especially if reapOnRead is false.
  - reap
```
public void reap()
```
    This method manually cleans up the reference queue to remove all garbage collected key/value pairs from the map. Calling this method is not needed if reapOnRead = true. Otherwise it might be a good idea to call this method when there is spare time (e.g. from a background thread).
    
    See Also:
    
    Information about the reapOnRead setting

Class WeakIdentityMap<K,V>

Method Summary

Methods inherited from class java.lang.Object

Method Detail

newHashMap

newHashMap

newConcurrentHashMap

newConcurrentHashMap

clear

containsKey

get

put

isEmpty

remove

size

keyIterator

valueIterator

reap