WeakIdentityMap (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.util, class: WeakIdentityMap

Package org.apache.lucene.util

# Class WeakIdentityMap<K,V>

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

  Modifier and Type
  Method
  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 Details

  - ### 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