com.bric.util

Class ObservableList<T>

  • All Implemented Interfaces:
    Iterable<T>, Collection<T>, List<T>, RandomAccess 

    public class ObservableList<T>
extends AbstractList<T>
implements RandomAccess
    This wraps an existing java.util.List in an observable structure.

    This is primarily intended for UI development, so the existing java.awt.event.ListDataListener interface is used to notify observers about changes to this list. (Debatably a better observer interface could be developed, but at least for the time being this doesn't seem necessary.)

    This object distinguishes between two types of listeners:

    • A synchronized listener (see addSynchronizedListener(ListDataListener, boolean)) will be notified in a way that guarantees the list has not been modified since the ListDataEvent occurred. That is: neither this listener nor any preceding synchronized listeners can modify this list.
    • An unsynchronized listener (see addUnsynchronizedListener(ListDataListener, boolean, boolean)) has the option to modify this list. And because any other preceding unsynchronized listener may have already modified this listener: it is not safe for an unsynchronized listener to assume the incoming ListDataEvent still contains valid indices.

    The level of detail used to calculate ListDataEvents will vary, depending on whether any attached listener asked for a high level of detail. Often in UIs a developer effectively needs a ChangeListener to indicate something (anything!) changed: if that is all you're interested in, then you can save some computational effort by not receiving highly detailed events. Many operations (such as set(int, Object) or remove(int)) always return precise events because they are trivial to compute, but set operations like retainAll(Collection) or setAll(List) can be expensive for large lists: in these methods the level of detail you asked for is taken into consideration.

    Threading and Synchronization

    This list is designed to support access from multiple threads. Any read-like operation (get(int), indexOf(Object), or even containsAll(Collection)) can run simultaneously with other read operations. However write-like operations (set(int, Object), clear(), setAll(List)) are mutually exclusive. Even read operations are not allowed during part of a write operation. (However once the operation itself is completed -- but before all listeners have completed -- read operations are allowed.)

    Because this list uses its own model of synchronization, it is not necessary for the underlying delegate list to be synchronized.

    Note however that if you bypass this ObservableList, then you have unsynchronized and unobserved changes: 

    ArrayList myList = new ArrayList();
ObservableList myObservableList = new ObservableList(myList);
myList.addAll(...);

    ListModels

    Also for further convenience this object has two methods related to ListModels:

    • getListModelEDTMirror(): this creates a separate list mirroring this list that is only ever updated in the event dispatch thread. Pro's: thread-safe. Con's: potentially expensive redundancy, and there will be (brief) times when the EDT still refers to elements you already removed.
    • getListModelView(boolean): this provides a real-time view of this list as a ListModel. Pro's: very light weight. Con's: if used in a JList, then this ObservableList should only ever be updated in the EDT.

    Implementation Details

    This class implements the RandomAccess interfaces, because most of the time this list is expected to delegate to list that implements RandomAccess, like the java.util.ArrayList. (The ArrayList is the default list model inside this list.) In the future if this becomes a questionable assumption we might introduce factory methods to create the appropriate ObservableList subclass.

    • Constructor Detail

      • ObservableList

        public ObservableList()
        Create a ObservableList using an ArrayList as its implementation.

      • ObservableList

        public ObservableList(T... elements)
        Create a ObservableList using an ArrayList as its implementation with the elements provided.

      • ObservableList

        public ObservableList(List<T> list)
        Create a ObservableList using the argument provided.

    • Method Detail

      • addSynchronizedListener

        public void addSynchronizedListener(ListDataListener listener,
                                    boolean detailedEvents)
        Adds a ListDataListener that will be notified of changes to this list in a synchronized lock. This lock guarantees that no other thread will alter the contents of this list until this listener returns control of the thread.

        For example: if this list received an addition then the listener's intervalAdded() method will be notified. Other threads may simultaneously poll this list (by calling get(int) or size() or even containsAll(Collection)), but no other thread can modify the contents of this list (for example by calling remove(int) or clear()) until this listener is finished processing the event.

        Because of this lock: it is important that synchronized listeners be relatively lightweight. If this listener can trigger a cascade of other listeners and complex operations: it should either:

        • Invoke those complicated operations later (in a separate thread, or by calling SwingUtilities.invokeLater(Runnable)), or
        • This listener should be an unsynchronized listener.

        Because there might be other ListDataListeners waiting to be notified when this listener returns, and because those listeners are also guaranteed that the list will exactly reflect the ListDataEvent they are receiving: this listener is not allowed to further modify this list. If this listener tries to modify this list (directly or indirectly) a RecursiveListenerModificationException will be thrown.

        Parameters:
        listener - the listener to add to this list.
        detailedEvents - if true then the ListDataEvents all listeners receive will be as detailed as possible. For example: when a complicated operation is performed (like retainAll(Collection) or setAll(List)) calculating a "detailed event" involves inspecting the before and after states of this list, and after reviewing 1,000,000 elements: it might be clear that the event the appropriate event is just a ListDataEvent.INTERVAL_REMOVED event of 2 elements. However if no listeners are interested in detailed events, then the same operation might notify listeners of a ListDataEvent.CONTENTS_CHANGED event ranging from elements [0, 1000000]. If you just want to know when something (anything) changed: then detailedEvents should be false for performance. But if you want to know more specific information, this argument should be true.
        listener - the listener to add to this list.
        See Also:
        removeSynchronizedListener(ListDataListener), addUnsynchronizedListener(ListDataListener, boolean, boolean)

      • addUnsynchronizedListener

        public void addUnsynchronizedListener(ListDataListener listener,
                                      boolean detailedEvents,
                                      boolean allowsModification)
        Add an unsynchronized ListDataListener that will be notified of changes to this list in an unprotected thread.

        For example: if an addition is made to this list, then the listener's intervalAdded() method is called. However during this method: another thread might call list.clear(), so the ListDataEvent the listener received may not contain specific reliable data anymore.

        This method should be used if the listener is not especially interested in specifics, or may be very expensive and cannot risk blocking further modifications for a long period of time.

        Parameters:
        listener - the listener to add to this list.
        detailedEvents - if true then the ListDataEvents all listeners receive will be as detailed as possible. For example: when a complicated operation is performed (like retainAll(Collection) or setAll(List)) calculating a "detailed event" involves inspecting the before and after states of this list, and after reviewing 1,000,000 elements: it might be clear that the event the appropriate event is just a ListDataEvent.INTERVAL_REMOVED event of 2 elements. However if no listeners are interested in detailed events, then the same operation might notify listeners of a ListDataEvent.CONTENTS_CHANGED event ranging from elements [0, 1000000]. If you just want to know when something (anything) changed: then detailedEvents should be false for performance. But if you want to know more specific information, this argument should be true.
        allowsModification - if this is false then and if this listener tries to further modify this list: a RecursiveListenerModificationException will be thrown. This is largely intended as a safeguard for developers to prevent against unintended looping/cascading listeners.
        See Also:
        removeUnsynchronizedListener(ListDataListener), addSynchronizedListener(ListDataListener, boolean)

      • addUnsynchronizedChangeListener

        public void addUnsynchronizedChangeListener(ChangeListener changeListener,
                                            boolean allowsModification)
        Add an unsynchronized ChangeListener that will be notified of changes to this list in an unprotected thread.
        Parameters:
        changeListener - the listener to add to this list.
        allowsModification - if this is false then and if this listener tries to further modify this list: a RecursiveListenerModificationException will be thrown. This is largely intended as a safeguard for developers to prevent against unintended looping/cascading listeners.
        See Also:
        removeUnsynchronizedChangeListener(ChangeListener), addUnsynchronizedListener(ListDataListener, boolean, boolean)

      • execute

        protected <R> R execute(com.bric.util.ObservableList.Operation<R> operation)
        This method executes all Operations, keeping thread safety and listeners in mind.
        Type Parameters:
        R - the parameterized type of the operation
        Parameters:
        operation - the operation to execute
        Returns:
        the return value of this operation

      • add

        public boolean add(T element)

      • add

        public void add(int index,
                T element)

      • addAll

        public boolean addAll(Collection<? extends T> collection)

      • addAll

        public boolean addAll(int index,
                      Collection<? extends T> collection)

      • addAll

        public boolean addAll(T... array)

      • addAll

        public boolean addAll(int index,
                      T... array)

      • clear

        public void clear()

      • removeRange

        public void removeRange(int index0,
                        int index1)
        Remove a range of elements from this list.
        Overrides:
        removeRange in class  AbstractList<T>
        Parameters:
        index0 - the first element to remove
        index1 - the last element to remove

      • remove

        public boolean remove(Object element)

      • remove

        public T remove(int index)

      • removeAll

        public boolean removeAll(Collection<?> collection)

      • removeAll

        public boolean removeAll(Object... array)

      • retainAll

        public boolean retainAll(Collection<?> collection)

      • retainAll

        public boolean retainAll(Object... array)

      • setAll

        public boolean setAll(List<T> newList)

      • setAll

        public boolean setAll(T... array)

      • set

        public T set(int index,
             T newElement)

      • get

        public T get(int index)

      • contains

        public boolean contains(Object element)

      • containsAll

        public boolean containsAll(Collection<?> collection)

      • containsAll

        public boolean containsAll(Object... array)

      • indexOf

        public int indexOf(Object element)

      • isEmpty

        public boolean isEmpty()

      • lastIndexOf

        public int lastIndexOf(Object element)

      • size

        public int size()

      • getListModelEDTMirror

        public ObservableList.EDTMirror<T> getListModelEDTMirror()
        This returns a non-mutable ListModel mirror of this list that is guaranteed to only update in the event dispatch thread.

        This is intended for JLists, or other UI elements.

        Because this is intentionally multithreaded: it is likely that this mirror will briefly contain outdated elements. That is to say: removing an element from this list does not mean the UI is done interacting with it.

        This mirror requires maintaining a separate copy of this list. Most references in Java are 8 bytes, so if you have a 1,024 element list: this list will be approximately 8KB, and each additional EDT mirror you construct will be another 8KB. This may be an acceptable amount (depending on how many of these lists you have), but if you have a 1,000,000-element list, then this list is about 8 MB, and each EDT mirror is another 8 MB. My point is: if this list may have several thousand elements, then this mirror is not trivial to construct and maintain.

        Returns:
        a non-mutable ListModel mirror of this list that is guaranteed to only update in the event dispatch thread.
        See Also:
        getListModelView(boolean)

      • getListModelEDTMirror

        public ObservableList.EDTMirror<T> getListModelEDTMirror(ObservableList.Filter<T> t)
        This returns a non-mutable ListModel mirror of this list that is guaranteed to only update in the event dispatch thread.

        This is intended for JLists, or other UI elements.

        Because this is intentionally multithreaded: it is likely that this mirror will briefly contain outdated elements. That is to say: removing an element from this list does not mean the UI is done interacting with it.

        This mirror requires maintaining a separate copy of this list. Most references in Java are 8 bytes, so if you have a 1,024 element list: this list will be approximately 8KB, and each additional EDT mirror you construct will be another 8KB. This may be an acceptable amount (depending on how many of these lists you have), but if you have a 1,000,000-element list, then this list is about 8 MB, and each EDT mirror is another 8 MB. My point is: if this list may have several thousand elements, then this mirror is not trivial to construct and maintain.

        Parameters:
        t - an optional filter that restricts what the mirrored list contains.
        Returns:
        a non-mutable ListModel mirror of this list that is guaranteed to only update in the event dispatch thread.
        See Also:
        getListModelView(boolean)

      • getListModelView

        public ListModel getListModelView(boolean updateListenersSynchronously)
        This returns a non-mutable ListModel view of this list. This ListModel notifies its listeners of changes exactly as they occur on the original thread.

        This view is an interface that interacts directly with this list; it is not a copy of this list like getListModelEDTMirror(). So if this list occupies 8 MB of memory: invoking this method will allocate less than 1 KB of memory.

        The downside to this view is: it does not make any guarantees regarding the event dispatch thread. So if this new ListModel is being used in a JList: you need to take responsibility to only update this list in the event dispatch thread.

        If the ObservableList implemented the ListModel interface: then this method wouldn't be unnecessary. (That is: the list model view and this list would be the same object.) The decision to not make this class a ListModel was a deliberate design choice to force developers to think about whether they needed a view or an EDT-specific mirror.

        See Also:
        getListModelEDTMirror()

      • clone

        public Object clone()
        Creates a ObservableList with the same list structure, but with no listeners.

      • equals

        public boolean equals(Object obj)

      • hashCode

        public int hashCode()

      • toString

        public String toString()

      • toArray

        public T[] toArray(Class<T> componentType)
        Create an array returning all the elements of this list.

        This method uses the existing read/write locking architecture the ObservableList uses, so it is safer than synchronizing this list to extract the elements separately.

        Parameters:
        componentType - the component type of the array.
        Returns:
        an array representation of all elements in this list.