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

    All Methods Static Methods Instance Methods Concrete Methods
    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 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