Package: groovy.util

## [Java] Class ObservableMap

- groovy.util.ObservableMap

- All Implemented Interfaces and Traits:
    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
    Modifiers | Name | Description
    --- | --- | ---
    `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.

  - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static String` | `CLEARED_PROPERTY` | Bound property name used for clear events.
    `static String` | `CONTENT_PROPERTY` | Bound property name for content changes.
    `static String` | `SIZE_PROPERTY` | Bound property name for map size changes.

  - ### Constructor Summary

    Constructors
    Constructor and 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.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `addPropertyChangeListener(PropertyChangeListener listener)` Registers a listener for all observable map events.
    `` | `public void` | `addPropertyChangeListener(String propertyName, PropertyChangeListener listener)` Registers a listener for a named bound property.
    `` | `public void` | `clear()` {@inheritDoc}
    `` | `public boolean` | `containsKey(Object key)` {@inheritDoc}
    `` | `public boolean` | `containsValue(Object value)` {@inheritDoc}
    `` | `public Set` | `entrySet()` {@inheritDoc}
    `` | `public boolean` | `equals(Object o)` {@inheritDoc}
    `` | `protected void` | `fireMultiPropertyEvent(List<PropertyEvent> events)` Fires a multi-property event from a list of events.
    `` | `protected void` | `fireMultiPropertyEvent(ObservableMap.PropertyEvent[] events)` Fires a multi-property event from an event array.
    `` | `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.
    `` | `public Object` | `get(Object key)` {@inheritDoc}
    `` | `public Map` | `getContent()` Returns an unmodifiable snapshot view of the backing map.
    `` | `protected Map` | `getMapDelegate()` Returns the mutable backing map.
    `` | `public PropertyChangeListener[]` | `getPropertyChangeListeners()` Returns listeners registered for all properties.
    `` | `public PropertyChangeListener[]` | `getPropertyChangeListeners(String propertyName)` Returns listeners registered for a named property.
    `` | `public int` | `getSize()` Returns the current map size as a bound property value.
    `` | `protected Closure` | `getTest()` Returns the optional event filter closure.
    `` | `public boolean` | `hasListeners(String propertyName)` Reports whether listeners are registered for a named property.
    `` | `public int` | `hashCode()` {@inheritDoc}
    `` | `public boolean` | `isEmpty()` {@inheritDoc}
    `` | `public Set` | `keySet()` {@inheritDoc}
    `` | `public Object` | `put(Object key, Object value)` {@inheritDoc}
    `` | `public void` | `putAll(Map map)` {@inheritDoc}
    `` | `public Object` | `remove(Object key)` {@inheritDoc}
    `` | `public void` | `removePropertyChangeListener(PropertyChangeListener listener)` Removes a listener registered for all properties.
    `` | `public void` | `removePropertyChangeListener(String propertyName, PropertyChangeListener listener)` Removes a listener registered for a named property.
    `` | `public int` | `size()` {@inheritDoc}
    `` | `public Collection` | `values()` {@inheritDoc}

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### public static final String CLEARED_PROPERTY

      Bound property name used for clear events.

    - #### public static final String CONTENT_PROPERTY

      Bound property name for content changes.

    - #### public static final String SIZE_PROPERTY

      Bound property name for map size changes.

  - ### Constructor Detail

    - #### public ObservableMap()

      Creates an observable map backed by a LinkedHashMap.

    - #### public ObservableMap(Closure test)

      Creates an observable map backed by a LinkedHashMap.

      Parameters:
        `test` - optional event filter

    - #### public ObservableMap(Map delegate)

      Creates an observable map backed by the supplied delegate.

      Parameters:
        `delegate` - the backing map

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

    - #### public void addPropertyChangeListener(PropertyChangeListener listener)

      Registers a listener for all observable map events.

      Parameters:
        `listener` - the listener to add

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

    - #### public void clear()

      {@inheritDoc}

    - #### public boolean containsKey(Object key)

      {@inheritDoc}

    - #### public boolean containsValue(Object value)

      {@inheritDoc}

    - #### public Set entrySet()

      {@inheritDoc}

    - #### public boolean equals(Object o)

      {@inheritDoc}

    - #### protected void fireMultiPropertyEvent(List<PropertyEvent> events)

      Fires a multi-property event from a list of events.

    - #### protected void fireMultiPropertyEvent(ObservableMap.PropertyEvent[] events)

      Fires a multi-property event from an event array.

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

    - #### public Object get(Object key)

      {@inheritDoc}

    - #### public Map getContent()

      Returns an unmodifiable snapshot view of the backing map.

      Returns:
        the map content

    - #### protected Map getMapDelegate()

      Returns the mutable backing map.

      Returns:
        the delegate map

    - #### public PropertyChangeListener[] getPropertyChangeListeners()

      Returns listeners registered for all properties.

      Returns:
        the registered listeners

    - #### public PropertyChangeListener[] getPropertyChangeListeners(String propertyName)

      Returns listeners registered for a named property.

      Parameters:
        `propertyName` - the observed property name
      Returns:
        the registered listeners

    - #### public int getSize()

      Returns the current map size as a bound property value.

      Returns:
        the current map size

    - #### protected Closure getTest()

      Returns the optional event filter closure.

      Returns:
        the event filter, or `null`

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

    - #### public int hashCode()

      {@inheritDoc}

    - #### public boolean isEmpty()

      {@inheritDoc}

    - #### public Set keySet()

      {@inheritDoc}

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

      {@inheritDoc}

    - #### public void putAll(Map map)

      {@inheritDoc}

    - #### public Object remove(Object key)

      {@inheritDoc}

    - #### public void removePropertyChangeListener(PropertyChangeListener listener)

      Removes a listener registered for all properties.

      Parameters:
        `listener` - the listener to remove

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

    - #### public int size()

      {@inheritDoc}

    - #### public Collection values()

      {@inheritDoc}