Package: org.codehaus.groovy.ast

## [Java] Interface NodeMetaDataHandler

-     public interface NodeMetaDataHandler

  An interface to mark a node being able to handle metadata.

  The default newMetaDataMap() returns a ListHashMap wrapped in Collections.synchronizedMap, so concurrent compiles sharing an AST node (e.g. built-in annotation `ClassNode`s cached by `ClassHelper`) cannot trip an `ArrayIndexOutOfBoundsException` during the array-to-HashMap transition in `ListHashMap.put`. Implementers that store the map in a field should declare it `volatile` so the unsynchronized fast-path read in the default methods sees publish-time writes.

  Since:
    3.0.0

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `copyNodeMetaData(NodeMetaDataHandler other)` Copies all node metadata from the other node to this one
    `` | `public Map<?, ?>` | `getMetaDataMap()` Returns the underlying metadata map.
    `<T>` | `public T` | `getNodeMetaData(Object key)` Gets the node metadata.
    `<T>` | `public T` | `getNodeMetaData(Object key, Function<?, ? extends T> valFn)` Gets the node metadata.
    `` | `public Map<?, ?>` | `getNodeMetaData()` Returns an unmodifiable snapshot of the current node metadata.
    `` | `private public Map` | `getOrCreateMetaDataMap()` Returns the existing metadata map, creating one via newMetaDataMap() on first use.
    `` | `public Map<?, ?>` | `newMetaDataMap()` Creates the backing metadata map.
    `` | `public Object` | `putNodeMetaData(Object key, Object value)` Sets the node metadata but allows overwriting values.
    `` | `public void` | `removeNodeMetaData(Object key)` Removes a node metadata entry.
    `` | `public void` | `setMetaDataMap(Map<?, ?> metaDataMap)`
    `` | `public void` | `setNodeMetaData(Object key, Object value)` Sets the node metadata.

- - ### Method Detail

    - #### public void copyNodeMetaData(NodeMetaDataHandler other)

      Copies all node metadata from the other node to this one

      Parameters:
        `other` - the other node

    - #### public Map<?, ?> getMetaDataMap()

      Returns the underlying metadata map. The map returned by the default newMetaDataMap() is internally synchronized, so individual `get`/`put`/`remove` calls are thread-safe; however, per the Collections.synchronizedMap contract, iteration over the returned map (or any of its `keySet`, `values`, or `entrySet` views) must be done inside a `synchronized (map) { ...` } block to avoid `ConcurrentModificationException`.

    - #### <T> public T getNodeMetaData(Object key)

      Gets the node metadata.

      Parameters:
        `key` - the metadata key
      Returns:
        the node metadata value for this key

    - #### <T> public T getNodeMetaData(Object key, Function<?, ? extends T> valFn)

      Gets the node metadata.

      Parameters:
        `key` - the metadata key
        `valFn` - the metadata value supplier
      Returns:
        the node metadata value for this key

    - #### public Map<?, ?> getNodeMetaData()

      Returns an unmodifiable snapshot of the current node metadata.

      Returns:
        the node metadata. Always not null.

    - #### private public Map getOrCreateMetaDataMap()

      Returns the existing metadata map, creating one via newMetaDataMap() on first use. Lazy creation is guarded by a brief lock on `this` so concurrent first-callers agree on a single map; subsequent callers see the map via the (volatile) field read and skip the lock entirely.

    - #### public Map<?, ?> newMetaDataMap()

      Creates the backing metadata map. The default returns a ListHashMap wrapped in Collections.synchronizedMap for thread-safe per-entry access; subclasses may override to supply an alternative map (e.g. for different memory/concurrency trade-offs).

      Since:
        5.0.0

    - #### public Object putNodeMetaData(Object key, Object value)

      Sets the node metadata but allows overwriting values.

      throws:
        GroovyBugError if key is null
      Parameters:
        `key` - the metadata key
        `value` - the metadata value
      Returns:
        the old node metadata value for this key

    - #### public void removeNodeMetaData(Object key)

      Removes a node metadata entry.

      throws:
        GroovyBugError if the key is null
      Parameters:
        `key` - the metadata key

    - #### public void setMetaDataMap(Map<?, ?> metaDataMap)

    - #### public void setNodeMetaData(Object key, Object value)

      Sets the node metadata.

      throws:
        GroovyBugError if key is null or there is already metadata for key
      Parameters:
        `key` - the metadata key
        `value` - the metadata value