Package groovy.util

# Class ObservableList

java.lang.Object
groovy.util.ObservableList

All Implemented Interfaces:
  `Iterable`, `Collection`, `List`

public class ObservableList extends Object implements List
List 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 ObservableList( {!(it instanceof Closure)} )

     // skip all properties whose name matches a regex
     def map = new ObservableList( { 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

- ObservableList.ElementAddedEvent - a new element is added to the list
- ObservableList.ElementRemovedEvent - an element is removed from the list
- ObservableList.ElementUpdatedEvent - an element changes value (same as regular PropertyChangeEvent)
- ObservableList.ElementClearedEvent - all elements have been removed from the list
- ObservableList.MultiElementAddedEvent - triggered by calling list.addAll()
- ObservableList.MultiElementRemovedEvent - triggered by calling list.removeAll()/list.retainAll()

Bound properties

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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `ObservableList.ChangeType`
  Enumerates the specialized list change events.
  `static class`
  `ObservableList.ElementAddedEvent`
  Event fired when one element is added.
  `static class`
  `ObservableList.ElementClearedEvent`
  Event fired when the list is cleared.
  `static class`
  `ObservableList.ElementEvent`
  Base event type for observable list content changes.
  `static class`
  `ObservableList.ElementRemovedEvent`
  Event fired when one element is removed.
  `static class`
  `ObservableList.ElementUpdatedEvent`
  Event fired when one element is updated.
  `static class`
  `ObservableList.MultiElementAddedEvent`
  Event fired when multiple elements are added.
  `static class`
  `ObservableList.MultiElementRemovedEvent`
  Event fired when multiple elements are removed.
  `protected class`
  `ObservableList.ObservableIterator`
  Iterator wrapper that reports removals as observable list events.
  `protected class`
  `ObservableList.ObservableListIterator`
  List iterator wrapper that routes mutations through `ObservableList`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `CONTENT_PROPERTY`
  Bound property name for list content changes.
  `static final String`
  `SIZE_PROPERTY`
  Bound property name for list size changes.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ObservableList()`
  Creates an observable list backed by an `ArrayList`.
  `ObservableList(Closure test)`
  Creates an observable list backed by an `ArrayList`.
  `ObservableList(List delegate)`
  Creates an observable list backed by the supplied delegate.
  `ObservableList(List delegate, Closure test)`
  Creates an observable list backed by the supplied delegate.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(int index, Object element)`
  `boolean`
  `add(Object o)`
  `boolean`
  `addAll(int index, Collection c)`
  `boolean`
  `addAll(Collection c)`
  `void`
  `addPropertyChangeListener(PropertyChangeListener listener)`
  Registers a listener for all observable list events.
  `void`
  `addPropertyChangeListener(String propertyName, PropertyChangeListener listener)`
  Registers a listener for a named bound property.
  `void`
  `clear()`
  `boolean`
  `contains(Object o)`
  `boolean`
  `containsAll(Collection c)`
  `boolean`
  `equals(Object o)`
  `protected void`
  `fireElementAddedEvent(int index, Object element)`
  Fires a single-element added event.
  `protected void`
  `fireElementClearedEvent(List values)`
  Fires a cleared event containing removed values.
  `protected void`
  `fireElementEvent(ObservableList.ElementEvent event)`
  Publishes an element event to registered listeners.
  `protected void`
  `fireElementRemovedEvent(int index, Object element)`
  Fires a single-element removed event.
  `protected void`
  `fireElementUpdatedEvent(int index, Object oldValue, Object newValue)`
  Fires a single-element updated event.
  `protected void`
  `fireMultiElementAddedEvent(int index, 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.
  `Object`
  `get(int index)`
  `List`
  `getContent()`
  Returns an unmodifiable snapshot view of the backing list.
  `protected List`
  `getDelegateList()`
  Returns the mutable backing list.
  `PropertyChangeListener[]`
  `getPropertyChangeListeners()`
  Returns listeners registered for all properties.
  `PropertyChangeListener[]`
  `getPropertyChangeListeners(String propertyName)`
  Returns listeners registered for a named property.
  `int`
  `getSize()`
  Returns the current list 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.
  `int`
  `indexOf(Object o)`
  `boolean`
  `isEmpty()`
  `Iterator`
  `iterator()`
  `int`
  `lastIndexOf(Object o)`
  `ListIterator`
  `listIterator()`
  `ListIterator`
  `listIterator(int index)`
  `Object`
  `remove(int index)`
  `boolean`
  `remove(Object o)`
  `boolean`
  `removeAll(Collection c)`
  `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.
  `boolean`
  `retainAll(Collection c)`
  `Object`
  `set(int index, Object element)`
  `int`
  `size()`
  `List`
  `subList(int fromIndex, int toIndex)`
  `Object[]`
  `toArray()`
  `Object[]`
  `toArray(Object[] a)`

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

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

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

  `parallelStream, removeIf, stream, toArray`

  ### Methods inherited from interface java.lang.Iterable

  `forEach`

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

  `replaceAll, sort, spliterator`

- ## Field Details

  - ### SIZE_PROPERTY

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

  - ### CONTENT_PROPERTY

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

- ## Constructor Details

  - ### ObservableList

    public ObservableList()
    Creates an observable list backed by an `ArrayList`.

  - ### ObservableList

    public ObservableList(List delegate)
    Creates an observable list backed by the supplied delegate.
    Parameters:
      `delegate` - the backing list

  - ### ObservableList

    public ObservableList(Closure test)
    Creates an observable list backed by an `ArrayList`.
    Parameters:
      `test` - optional event filter

  - ### ObservableList

    public ObservableList(List delegate, Closure test)
    Creates an observable list backed by the supplied delegate.
    Parameters:
      `delegate` - the backing list
      `test` - optional event filter

- ## Method Details

  - ### getContent

    public List getContent()
    Returns an unmodifiable snapshot view of the backing list.
    Returns:
      the list content

  - ### getDelegateList

    protected List getDelegateList()
    Returns the mutable backing list.
    Returns:
      the delegate list

  - ### getTest

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

  - ### fireElementAddedEvent

    protected void fireElementAddedEvent(int index, Object element)
    Fires a single-element added event.

  - ### fireMultiElementAddedEvent

    protected void fireMultiElementAddedEvent(int index, List values)
    Fires a multi-element added event.

  - ### fireElementClearedEvent

    protected void fireElementClearedEvent(List values)
    Fires a cleared event containing removed values.

  - ### fireElementRemovedEvent

    protected void fireElementRemovedEvent(int index, Object element)
    Fires a single-element removed event.

  - ### fireMultiElementRemovedEvent

    protected void fireMultiElementRemovedEvent(List values)
    Fires a multi-element removed event.

  - ### fireElementUpdatedEvent

    protected void fireElementUpdatedEvent(int index, Object oldValue, Object newValue)
    Fires a single-element updated event.

  - ### fireElementEvent

    protected void fireElementEvent(ObservableList.ElementEvent event)
    Publishes an element event to registered listeners.

  - ### fireSizeChangedEvent

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

  - ### add

    public void add(int index, Object element)
    Specified by:
      `add` in interface `List`

  - ### add

    public boolean add(Object o)
    Specified by:
      `add` in interface `Collection`
    Specified by:
      `add` in interface `List`

  - ### addAll

    public boolean addAll(Collection c)
    Specified by:
      `addAll` in interface `Collection`
    Specified by:
      `addAll` in interface `List`

  - ### addAll

    public boolean addAll(int index, Collection c)
    Specified by:
      `addAll` in interface `List`

  - ### clear

    public void clear()
    Specified by:
      `clear` in interface `Collection`
    Specified by:
      `clear` in interface `List`

  - ### contains

    public boolean contains(Object o)
    Specified by:
      `contains` in interface `Collection`
    Specified by:
      `contains` in interface `List`

  - ### containsAll

    public boolean containsAll(Collection c)
    Specified by:
      `containsAll` in interface `Collection`
    Specified by:
      `containsAll` in interface `List`

  - ### equals

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

  - ### get

    public Object get(int index)
    Specified by:
      `get` in interface `List`

  - ### hashCode

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

  - ### indexOf

    public int indexOf(Object o)
    Specified by:
      `indexOf` in interface `List`

  - ### isEmpty

    public boolean isEmpty()
    Specified by:
      `isEmpty` in interface `Collection`
    Specified by:
      `isEmpty` in interface `List`

  - ### iterator

    public Iterator iterator()
    Specified by:
      `iterator` in interface `Collection`
    Specified by:
      `iterator` in interface `Iterable`
    Specified by:
      `iterator` in interface `List`

  - ### lastIndexOf

    public int lastIndexOf(Object o)
    Specified by:
      `lastIndexOf` in interface `List`

  - ### listIterator

    public ListIterator listIterator()
    Specified by:
      `listIterator` in interface `List`

  - ### listIterator

    public ListIterator listIterator(int index)
    Specified by:
      `listIterator` in interface `List`

  - ### remove

    public Object remove(int index)
    Specified by:
      `remove` in interface `List`

  - ### remove

    public boolean remove(Object o)
    Specified by:
      `remove` in interface `Collection`
    Specified by:
      `remove` in interface `List`

  - ### removeAll

    public boolean removeAll(Collection c)
    Specified by:
      `removeAll` in interface `Collection`
    Specified by:
      `removeAll` in interface `List`

  - ### retainAll

    public boolean retainAll(Collection c)
    Specified by:
      `retainAll` in interface `Collection`
    Specified by:
      `retainAll` in interface `List`

  - ### set

    public Object set(int index, Object element)
    Specified by:
      `set` in interface `List`

  - ### size

    public int size()
    Specified by:
      `size` in interface `Collection`
    Specified by:
      `size` in interface `List`

  - ### getSize

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

  - ### subList

    public List subList(int fromIndex, int toIndex)
    Specified by:
      `subList` in interface `List`

  - ### toArray

    public Object[] toArray()
    Specified by:
      `toArray` in interface `Collection`
    Specified by:
      `toArray` in interface `List`

  - ### toArray

    public Object[] toArray(Object[] a)
    Specified by:
      `toArray` in interface `Collection`
    Specified by:
      `toArray` in interface `List`

  - ### addPropertyChangeListener

    public void addPropertyChangeListener(PropertyChangeListener listener)
    Registers a listener for all observable list 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