Package: groovy.util

## [Java] Class ObservableSet<E>

- groovy.util.ObservableSet

- All Implemented Interfaces and Traits:
    Set

      public class ObservableSet<E>
      extends Object
      implements Set

  Set 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 set = new ObservableSet( {!(it instanceof Closure)} )
       <p/>
       // skip all properties whose name matches a regex
       def set = new ObservableSet( { 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
  - ObservableSet.ElementAddedEvent - a new element is added to the set
  - ObservableSet.ElementRemovedEvent - an element is removed from the set
  - ObservableSet.ElementUpdatedEvent - an element changes value (same as regular PropertyChangeEvent)
  - ObservableSet.ElementClearedEvent - all elements have been removed from the list
  - ObservableSet.MultiElementAddedEvent - triggered by calling set.addAll()
  - ObservableSet.MultiElementRemovedEvent - triggered by calling set.removeAll()/set.retainAll()

  Bound properties

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

- - ### Nested Class Summary

    Nested classes
    Modifiers | Name | Description
    --- | --- | ---
    `enum` | `ObservableSet.ChangeType` | Enumerates the specialized set change events.
    `static class` | `ObservableSet.ElementAddedEvent` | Event fired when one element is added.
    `static class` | `ObservableSet.ElementClearedEvent` | Event fired when the set is cleared.
    `static class` | `ObservableSet.ElementEvent` | Base event type for observable set content changes.
    `static class` | `ObservableSet.ElementRemovedEvent` | Event fired when one element is removed.
    `static class` | `ObservableSet.MultiElementAddedEvent` | Event fired when multiple elements are added.
    `static class` | `ObservableSet.MultiElementRemovedEvent` | Event fired when multiple elements are removed.
    `protected class` | `ObservableSet.ObservableIterator` | Iterator wrapper that reports removals as observable set events.

  - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static String` | `CONTENT_PROPERTY` | Bound property name for set content changes.
    `static String` | `SIZE_PROPERTY` | Bound property name for set size changes.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `ObservableSet()` Creates an observable set backed by a HashSet.
    `ObservableSet(Set<E> delegate)` Creates an observable set backed by the supplied delegate.
    `ObservableSet(Closure test)` Creates an observable set backed by a HashSet.
    `ObservableSet(Set<E> delegate, Closure test)` Creates an observable set backed by the supplied delegate.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public boolean` | `add(E e)` {@inheritDoc}
    `` | `public boolean` | `addAll(Collection<? extends E> c)` {@inheritDoc}
    `` | `public void` | `addPropertyChangeListener(PropertyChangeListener listener)` Registers a listener for all observable set events.
    `` | `public void` | `addPropertyChangeListener(String propertyName, PropertyChangeListener listener)` Registers a listener for a named bound property.
    `` | `public void` | `clear()` {@inheritDoc}
    `` | `public boolean` | `contains(Object o)` {@inheritDoc}
    `` | `public boolean` | `containsAll(Collection<?> objects)` {@inheritDoc}
    `` | `protected void` | `fireElementAddedEvent(Object element)` Fires a single-element added event.
    `` | `protected void` | `fireElementClearedEvent(List values)` Fires a cleared event containing removed values.
    `` | `protected void` | `fireElementEvent(ObservableSet.ElementEvent event)` Publishes an element event to registered listeners.
    `` | `protected void` | `fireElementRemovedEvent(Object element)` Fires a single-element removed event.
    `` | `protected void` | `fireMultiElementAddedEvent(List values)` Fires a multi-element added event.
    `` | `protected void` | `fireMultiElementRemovedEvent(List values)` Fires a multi-element removed event.
    `` | `protected void` | `fireSizeChangedEvent(int oldValue, int newValue)` Fires the bound size change event.
    `` | `public Set<E>` | `getContent()` Returns an unmodifiable snapshot view of the backing set.
    `` | `protected Set<E>` | `getDelegateSet()` Returns the mutable backing set.
    `` | `public PropertyChangeListener[]` | `getPropertyChangeListeners()` Returns listeners registered for all properties.
    `` | `public PropertyChangeListener[]` | `getPropertyChangeListeners(String propertyName)` Returns listeners registered for a named property.
    `` | `protected Closure` | `getTest()` Returns the optional event filter closure.
    `` | `public boolean` | `hasListeners(String propertyName)` Reports whether listeners are registered for a named property.
    `` | `public boolean` | `isEmpty()` {@inheritDoc}
    `` | `public Iterator<E>` | `iterator()` {@inheritDoc}
    `` | `public boolean` | `remove(Object o)` {@inheritDoc}
    `` | `public boolean` | `removeAll(Collection<?> c)` {@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 boolean` | `retainAll(Collection<?> c)` {@inheritDoc}
    `` | `public int` | `size()` {@inheritDoc}
    `` | `public Object[]` | `toArray()` {@inheritDoc}
    `<T>` | `public T[]` | `toArray(T[] ts)` {@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 CONTENT_PROPERTY

      Bound property name for set content changes.

    - #### public static final String SIZE_PROPERTY

      Bound property name for set size changes.

  - ### Constructor Detail

    - #### public ObservableSet()

      Creates an observable set backed by a HashSet.

    - #### public ObservableSet(Set<E> delegate)

      Creates an observable set backed by the supplied delegate.

      Parameters:
        `delegate` - the backing set

    - #### public ObservableSet(Closure test)

      Creates an observable set backed by a HashSet.

      Parameters:
        `test` - optional event filter

    - #### public ObservableSet(Set<E> delegate, Closure test)

      Creates an observable set backed by the supplied delegate.

      Parameters:
        `delegate` - the backing set
        `test` - optional event filter

  - ### Method Detail

    - #### public boolean add(E e)

      {@inheritDoc}

    - #### public boolean addAll(Collection<? extends E> c)

      {@inheritDoc}

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

      Registers a listener for all observable set 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 contains(Object o)

      {@inheritDoc}

    - #### public boolean containsAll(Collection<?> objects)

      {@inheritDoc}

    - #### protected void fireElementAddedEvent(Object element)

      Fires a single-element added event.

    - #### protected void fireElementClearedEvent(List values)

      Fires a cleared event containing removed values.

    - #### protected void fireElementEvent(ObservableSet.ElementEvent event)

      Publishes an element event to registered listeners.

    - #### protected void fireElementRemovedEvent(Object element)

      Fires a single-element removed event.

    - #### protected void fireMultiElementAddedEvent(List values)

      Fires a multi-element added event.

    - #### protected void fireMultiElementRemovedEvent(List values)

      Fires a multi-element removed event.

    - #### protected void fireSizeChangedEvent(int oldValue, int newValue)

      Fires the bound size change event.

    - #### public Set<E> getContent()

      Returns an unmodifiable snapshot view of the backing set.

      Returns:
        the set content

    - #### protected Set<E> getDelegateSet()

      Returns the mutable backing set.

      Returns:
        the delegate set

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

    - #### 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 boolean isEmpty()

      {@inheritDoc}

    - #### public Iterator<E> iterator()

      {@inheritDoc}

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

      {@inheritDoc}

    - #### public boolean removeAll(Collection<?> c)

      {@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 boolean retainAll(Collection<?> c)

      {@inheritDoc}

    - #### public int size()

      {@inheritDoc}

    - #### public Object[] toArray()

      {@inheritDoc}

    - #### <T> public T[] toArray(T[] ts)

      {@inheritDoc}