Package groovy.util

# Class ObservableMap

java.lang.Object
groovy.util.ObservableMap

All Implemented Interfaces:
  `Map`

public class ObservableMap extends Object implements Map
Map decorator that will trigger PropertyChangeEvents when a value changes.
An optional Closure may be specified and will work as a filter, if it returns true the property will trigger an event (if the value indeed changed), otherwise it won't. The Closure may receive 1 or 2 parameters, the single one being the value, the other one both the key and value, for example:

     // skip all properties whose value is a closure
     def map = new ObservableMap( {!(it instanceof Closure)} )

     // skip all properties whose name matches a regex
     def map = new ObservableMap( { name, value -> !(name =~ /[A-Z+]/) } )

The current implementation will trigger specialized events in the following scenarios, you need not register a different listener as those events extend from PropertyChangeEvent

- ObservableMap.PropertyAddedEvent - a new property is added to the map
- ObservableMap.PropertyRemovedEvent - a property is removed from the map
- ObservableMap.PropertyUpdatedEvent - a property changes value (same as regular PropertyChangeEvent)
- ObservableMap.PropertyClearedEvent - all properties have been removed from the map
- ObservableMap.MultiPropertyEvent - triggered by calling map.putAll(), contains Added|Updated events

Bound properties

- `content` - read-only.
- `size` - read-only.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `ObservableMap.ChangeType`
  Enumerates the specialized map change events.
  `static class`
  `ObservableMap.MultiPropertyEvent`
  Event fired when multiple property changes are aggregated.
  `static class`
  `ObservableMap.PropertyAddedEvent`
  Event fired when a property is added.
  `static class`
  `ObservableMap.PropertyClearedEvent`
  Event fired when the map is cleared.
  `static class`
  `ObservableMap.PropertyEvent`
  Base event type for observable map changes.
  `static class`
  `ObservableMap.PropertyRemovedEvent`
  Event fired when a property is removed.
  `static class`
  `ObservableMap.PropertyUpdatedEvent`
  Event fired when a property value changes.

  ## Nested classes/interfaces inherited from interface java.util.Map

  `Map.Entry<K extends Object,V extends Object>`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `CLEARED_PROPERTY`
  Bound property name used for clear events.
  `static final String`
  `CONTENT_PROPERTY`
  Bound property name for content changes.
  `static final String`
  `SIZE_PROPERTY`
  Bound property name for map size changes.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ObservableMap()`
  Creates an observable map backed by a `LinkedHashMap`.
  `ObservableMap(Closure test)`
  Creates an observable map backed by a `LinkedHashMap`.
  `ObservableMap(Map delegate)`
  Creates an observable map backed by the supplied delegate.
  `ObservableMap(Map delegate, Closure test)`
  Creates an observable map backed by the supplied delegate.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addPropertyChangeListener(PropertyChangeListener listener)`
  Registers a listener for all observable map events.
  `void`
  `addPropertyChangeListener(String propertyName, PropertyChangeListener listener)`
  Registers a listener for a named bound property.
  `void`
  `clear()`
  `boolean`
  `containsKey(Object key)`
  `boolean`
  `containsValue(Object value)`
  `Set`
  `entrySet()`
  `boolean`
  `equals(Object o)`
  `protected void`
  `fireMultiPropertyEvent(ObservableMap.PropertyEvent[] events)`
  Fires a multi-property event from an event array.
  `protected void`
  `fireMultiPropertyEvent(List<ObservableMap.PropertyEvent> events)`
  Fires a multi-property event from a list of events.
  `protected void`
  `firePropertyAddedEvent(Object key, Object value)`
  Fires a property-added event.
  `protected void`
  `firePropertyClearedEvent(Map values)`
  Fires a map-cleared event.
  `protected void`
  `firePropertyEvent(ObservableMap.PropertyEvent event)`
  Publishes a property event to registered listeners.
  `protected void`
  `firePropertyRemovedEvent(Object key, Object value)`
  Fires a property-removed event.
  `protected void`
  `firePropertyUpdatedEvent(Object key, Object oldValue, Object newValue)`
  Fires a property-updated event.
  `protected void`
  `fireSizeChangedEvent(int oldValue, int newValue)`
  Fires the bound size change event.
  `Object`
  `get(Object key)`
  `Map`
  `getContent()`
  Returns an unmodifiable snapshot view of the backing map.
  `protected Map`
  `getMapDelegate()`
  Returns the mutable backing map.
  `PropertyChangeListener[]`
  `getPropertyChangeListeners()`
  Returns listeners registered for all properties.
  `PropertyChangeListener[]`
  `getPropertyChangeListeners(String propertyName)`
  Returns listeners registered for a named property.
  `int`
  `getSize()`
  Returns the current map size as a bound property value.
  `protected Closure`
  `getTest()`
  Returns the optional event filter closure.
  `int`
  `hashCode()`
  `boolean`
  `hasListeners(String propertyName)`
  Reports whether listeners are registered for a named property.
  `boolean`
  `isEmpty()`
  `Set`
  `keySet()`
  `Object`
  `put(Object key, Object value)`
  `void`
  `putAll(Map map)`
  `Object`
  `remove(Object key)`
  `void`
  `removePropertyChangeListener(PropertyChangeListener listener)`
  Removes a listener registered for all properties.
  `void`
  `removePropertyChangeListener(String propertyName, PropertyChangeListener listener)`
  Removes a listener registered for a named property.
  `int`
  `size()`
  `Collection`
  `values()`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface java.util.Map

  `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

- ## Field Details

  - ### SIZE_PROPERTY

    public static final String SIZE_PROPERTY
    Bound property name for map size changes.
    See Also:
      - Constant Field Values

  - ### CONTENT_PROPERTY

    public static final String CONTENT_PROPERTY
    Bound property name for content changes.
    See Also:
      - Constant Field Values

  - ### CLEARED_PROPERTY

    public static final String CLEARED_PROPERTY
    Bound property name used for clear events.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### ObservableMap

    public ObservableMap()
    Creates an observable map backed by a `LinkedHashMap`.

  - ### ObservableMap

    public ObservableMap(Closure test)
    Creates an observable map backed by a `LinkedHashMap`.
    Parameters:
      `test` - optional event filter

  - ### ObservableMap

    public ObservableMap(Map delegate)
    Creates an observable map backed by the supplied delegate.
    Parameters:
      `delegate` - the backing map

  - ### ObservableMap

    public ObservableMap(Map delegate, Closure test)
    Creates an observable map backed by the supplied delegate.
    Parameters:
      `delegate` - the backing map
      `test` - optional event filter

- ## Method Details

  - ### getMapDelegate

    protected Map getMapDelegate()
    Returns the mutable backing map.
    Returns:
      the delegate map

  - ### getTest

    protected Closure getTest()
    Returns the optional event filter closure.
    Returns:
      the event filter, or `null`

  - ### getContent

    public Map getContent()
    Returns an unmodifiable snapshot view of the backing map.
    Returns:
      the map content

  - ### firePropertyClearedEvent

    protected void firePropertyClearedEvent(Map values)
    Fires a map-cleared event.

  - ### firePropertyAddedEvent

    protected void firePropertyAddedEvent(Object key, Object value)
    Fires a property-added event.

  - ### firePropertyUpdatedEvent

    protected void firePropertyUpdatedEvent(Object key, Object oldValue, Object newValue)
    Fires a property-updated event.

  - ### fireMultiPropertyEvent

    protected void fireMultiPropertyEvent(List<ObservableMap.PropertyEvent> events)
    Fires a multi-property event from a list of events.

  - ### fireMultiPropertyEvent

    protected void fireMultiPropertyEvent(ObservableMap.PropertyEvent[] events)
    Fires a multi-property event from an event array.

  - ### firePropertyRemovedEvent

    protected void firePropertyRemovedEvent(Object key, Object value)
    Fires a property-removed event.

  - ### firePropertyEvent

    protected void firePropertyEvent(ObservableMap.PropertyEvent event)
    Publishes a property event to registered listeners.

  - ### fireSizeChangedEvent

    protected void fireSizeChangedEvent(int oldValue, int newValue)
    Fires the bound size change event.

  - ### clear

    public void clear()
    Specified by:
      `clear` in interface `Map`

  - ### containsKey

    public boolean containsKey(Object key)
    Specified by:
      `containsKey` in interface `Map`

  - ### containsValue

    public boolean containsValue(Object value)
    Specified by:
      `containsValue` in interface `Map`

  - ### entrySet

    public Set entrySet()
    Specified by:
      `entrySet` in interface `Map`

  - ### equals

    public boolean equals(Object o)
    Specified by:
      `equals` in interface `Map`
    Overrides:
      `equals` in class `Object`

  - ### get

    public Object get(Object key)
    Specified by:
      `get` in interface `Map`

  - ### hashCode

    public int hashCode()
    Specified by:
      `hashCode` in interface `Map`
    Overrides:
      `hashCode` in class `Object`

  - ### isEmpty

    public boolean isEmpty()
    Specified by:
      `isEmpty` in interface `Map`

  - ### keySet

    public Set keySet()
    Specified by:
      `keySet` in interface `Map`

  - ### put

    public Object put(Object key, Object value)
    Specified by:
      `put` in interface `Map`

  - ### putAll

    public void putAll(Map map)
    Specified by:
      `putAll` in interface `Map`

  - ### remove

    public Object remove(Object key)
    Specified by:
      `remove` in interface `Map`

  - ### size

    public int size()
    Specified by:
      `size` in interface `Map`

  - ### getSize

    public int getSize()
    Returns the current map size as a bound property value.
    Returns:
      the current map size

  - ### values

    public Collection values()
    Specified by:
      `values` in interface `Map`

  - ### addPropertyChangeListener

    public void addPropertyChangeListener(PropertyChangeListener listener)
    Registers a listener for all observable map events.
    Parameters:
      `listener` - the listener to add

  - ### addPropertyChangeListener

    public void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)
    Registers a listener for a named bound property.
    Parameters:
      `propertyName` - the property to observe
      `listener` - the listener to add

  - ### getPropertyChangeListeners

    public PropertyChangeListener[] getPropertyChangeListeners()
    Returns listeners registered for all properties.
    Returns:
      the registered listeners

  - ### getPropertyChangeListeners

    public PropertyChangeListener[] getPropertyChangeListeners(String propertyName)
    Returns listeners registered for a named property.
    Parameters:
      `propertyName` - the observed property name
    Returns:
      the registered listeners

  - ### removePropertyChangeListener

    public void removePropertyChangeListener(PropertyChangeListener listener)
    Removes a listener registered for all properties.
    Parameters:
      `listener` - the listener to remove

  - ### removePropertyChangeListener

    public void removePropertyChangeListener(String propertyName, PropertyChangeListener listener)
    Removes a listener registered for a named property.
    Parameters:
      `propertyName` - the observed property name
      `listener` - the listener to remove

  - ### hasListeners

    public boolean hasListeners(String propertyName)
    Reports whether listeners are registered for a named property.
    Parameters:
      `propertyName` - the property name to inspect
    Returns:
      `true` if listeners are registered