ca.odell.glazedlists
Class SeparatorList<E>

java.lang.Object
  ca.odell.glazedlists.AbstractEventList<E>
      ca.odell.glazedlists.TransformedList<E,E>
          ca.odell.glazedlists.SeparatorList<E>

All Implemented Interfaces:

ListEventListener<E>, EventList<E>, Iterable<E>, Collection<E>, EventListener, List<E>

public class SeparatorList<E>
extends TransformedList<E,E>

A list that adds separator objects before each group of elements.

SeparatorList is writable, however, attempts to write over separators will always produce an IllegalArgumentException. For example, calling TransformedList.add(int, Object), TransformedList.set(int, Object) or TransformedList.remove(int) with a an index that actually corresponds to a separator in this list will produce an IllegalArgumentException. This is because there is no corresponding index for separators in the source list; separators are added by this SeparatorList. All index-based write operations must be performed on indexes known to correspond to non-separator elements.

Warning: this class won't work very well with generics because separators are mixed in, which will be a different class than the other list elements.

Warning: This class is thread ready but not thread safe. See EventList for an example of thread safe code.

Developer Preview this class is still under heavy development and subject to API changes. It's also really slow at the moment and won't scale to lists of size larger than a hundred or so efficiently.

Author:

Jesse Wilson

Nested Class Summary

static interface

SeparatorList.Separator<E> A separator heading the elements of a group.

Field Summary

Fields inherited from class ca.odell.glazedlists.TransformedList

source

Fields inherited from class ca.odell.glazedlists.AbstractEventList

publisher, readWriteLock, updates

Constructor Summary

SeparatorList(EventList<E> source, Comparator<? super E> comparator, int minimumSizeForSeparator, int defaultLimit)
Construct a SeparatorList overtop of the source list by using the given comparator to compute groups of similar source items.

Method Summary

void	dispose() Releases the resources consumed by this TransformedList so that it may eventually be garbage collected.
protected int	getSourceIndex(int mutationIndex) Gets the index in the source EventList that corresponds to the specified index.
protected boolean	isWritable() Gets whether the source EventList is writable via this API.
void	listChanged(ListEvent<E> listChanges) When the underlying list changes, this notification allows the object to repaint itself or update itself as necessary.
void	setComparator(Comparator<E> comparator) Set the Comparator used to determine how elements are split into groups.
int	size() Returns the number of elements in this list.

Methods inherited from class ca.odell.glazedlists.TransformedList

add, addAll, clear, get, remove, removeAll, retainAll, set

Methods inherited from class ca.odell.glazedlists.AbstractEventList

add, addAll, addListEventListener, contains, containsAll, equals, getPublisher, getReadWriteLock, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, removeListEventListener, subList, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SeparatorList

public SeparatorList(EventList<E> source,
                     Comparator<? super E> comparator,
                     int minimumSizeForSeparator,
                     int defaultLimit)

Construct a SeparatorList overtop of the source list by using the given comparator to compute groups of similar source items. For each group a single separator will be present in this SeparatorList provided the group contains at least the minimumSizeForSeparator number of items (otherwise they are left without a separator). In addition this SeparatorList will never show more than the defaultLimit number of group elements from any given group.

Parameters:

source - the list containing the raw items to be grouped

comparator - the Comparator which defines the grouping logic

minimumSizeForSeparator - the number of elements which must exist in a group in order for a separator to be created

defaultLimit - the maximum number of element to display for a group; extra elements are truncated

Method Detail

size

public int size()

Returns the number of elements in this list. If this list contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:

size in interface Collection<E>

Specified by:

size in interface List<E>

Overrides:

size in class TransformedList<E,E>

Returns:

the number of elements in this list.

getSourceIndex

protected int getSourceIndex(int mutationIndex)

Gets the index in the source EventList that corresponds to the specified index. More formally, returns the index such that
this.get(i) == source.get(getSourceIndex(i)) for all legal values of i.

Overrides:

getSourceIndex in class TransformedList<E,E>

isWritable

protected boolean isWritable()

Gets whether the source EventList is writable via this API.

Extending classes must override this method in order to make themselves writable.

Specified by:

isWritable in class TransformedList<E,E>

setComparator

public void setComparator(Comparator<E> comparator)

Set the Comparator used to determine how elements are split into groups.

Performance Note: sorting will take O(N * Log N) time.

Warning: This method is thread ready but not thread safe. See EventList for an example of thread safe code.

listChanged

public void listChanged(ListEvent<E> listChanges)

When the underlying list changes, this notification allows the object to repaint itself or update itself as necessary.

It is mandatory that the calling thread has obtained the write lock on the source list. This is because the calling thread will have written to the source list to cause this event. This condition guarantees that no writes can occur while the listener is handling this event. It is an error to write to the source list while processing an event.

Specified by:

listChanged in interface ListEventListener<E>

Specified by:

listChanged in class TransformedList<E,E>

Parameters:

listChanges - a ListEvent describing the changes to the list

dispose

public void dispose()

Releases the resources consumed by this TransformedList so that it may eventually be garbage collected.

A TransformedList will be garbage collected without a call to TransformedList.dispose(), but not before its source EventList is garbage collected. By calling TransformedList.dispose(), you allow the TransformedList to be garbage collected before its source EventList. This is necessary for situations where a TransformedList is short-lived but its source EventList is long-lived.

Warning: It is an error to call any method on a TransformedList after it has been disposed.

Specified by:

dispose in interface EventList<E>

Overrides:

dispose in class TransformedList<E,E>