com.levigo.util.base.glazedlists
Class GroupingList<E>

java.lang.Object
  com.levigo.util.base.glazedlists.AbstractEventList<E>
      com.levigo.util.base.glazedlists.TransformedList<E,List<E>>
          com.levigo.util.base.glazedlists.GroupingList<E>

All Implemented Interfaces:

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

public final class GroupingList<E>
extends TransformedList<E,List<E>>

A grouping list contains elements which are themselves Lists. Those Lists are infact elements of the source list which have been grouped together into a List. The logic of how to group the source elements is specified via a Comparator. Elements for which the Comparator returns 0 are guaranteed to be contained within the same group within this GroupingList. This implies that source elements may only participate in a single group within this GroupingList.

Further transformations may be layered on top of this GroupingList to transform the group lists into any other desirable form.

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

EventList Overview

Overview

Writable:	yes
Concurrency:	thread ready, not thread safe
Performance:	reads: O(log N), writes O(log N)
Memory:
Unit Tests:	GroupingListTest
Issues:	281

Author:

James Lemieux

Field Summary

Fields inherited from class com.levigo.util.base.glazedlists.TransformedList

source

Fields inherited from class com.levigo.util.base.glazedlists.AbstractEventList

publisher, readWriteLock, updates

Constructor Summary

GroupingList(EventList<E> source)
Creates a GroupingList that determines groupings via the Comparable interface which all elements of the source are assumed to implement.

GroupingList(EventList<E> source, Comparator<? super E> comparator)
Creates a GroupingList that determines groups using the specified Comparator.

Method Summary

void	add(int index, List<E> value) This version of add will distribute all elements within the given value List into groups.
static <E extends Comparable<? super E>> GroupingList<E>	create(EventList<E> source) Creates a GroupingList that determines groupings via the Comparable interface which all elements of the source are assumed to implement.
void	dispose() Releases the resources consumed by this TransformedList so that it may eventually be garbage collected.
List<E>	get(int index) Returns the element at the specified position in this list.
protected int	getSourceIndex(int index) Gets the index in the source EventList that corresponds to the specified index.
int	indexOfGroup(E groupElement) Return the index of the group to which the groupElement would belong if it were hypothetically added to the source list.
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.
List<E>	remove(int index) Removes the element at the specified position in this list (optional operation).
List<E>	set(int index, List<E> value) Replaces the element at the specified position in this list with the specified element (optional operation).
void	setComparator(Comparator<? super E> comparator) Change the Comparator which determines the groupings presented by this List
int	size() Returns the number of elements in this list.

Methods inherited from class com.levigo.util.base.glazedlists.TransformedList

addAll, clear, removeAll, retainAll

Methods inherited from class com.levigo.util.base.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

GroupingList

public GroupingList(EventList<E> source)

Creates a GroupingList that determines groupings via the Comparable interface which all elements of the source are assumed to implement.

Usage of factory method create(EventList) is preferable.

GroupingList

public GroupingList(EventList<E> source,
                    Comparator<? super E> comparator)

Creates a GroupingList that determines groups using the specified Comparator.

Parameters:

source - the EventList containing elements to be grouped

comparator - the Comparator used to determine groupings

Method Detail

create

public static <E extends Comparable<? super E>> GroupingList<E> create(EventList<E> source)

Creates a GroupingList that determines groupings via the Comparable interface which all elements of the source are assumed to implement.

indexOfGroup

public int indexOfGroup(E groupElement)

Return the index of the group to which the groupElement would belong if it were hypothetically added to the source list. Note that groupElement does NOT have to exist in a group. This method is essentially a convenient way to locate a group based on a prototypical element of that group.

Parameters:

groupElement - a prototype element of the group to locate

Returns:

the index of the group that would contain groupElement if it were added to the source list or -1 if no currently existing group would contain the groupElement

setComparator

public void setComparator(Comparator<? super E> comparator)

Change the Comparator which determines the groupings presented by this List

Parameters:

comparator - the Comparator used to determine groupings; null will be treated as GlazedLists.comparableComparator()

getSourceIndex

protected int getSourceIndex(int index)

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,List<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,List<E>>

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,List<E>>

get

public List<E> get(int index)

Returns the element at the specified position in this list.

Specified by:

get in interface List<List<E>>

Overrides:

get in class TransformedList<E,List<E>>

Parameters:

index - index of element to return.

Returns:

the element at the specified position in this list.

remove

public List<E> remove(int index)

Removes the element at the specified position in this list (optional operation). Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.

Specified by:

remove in interface List<List<E>>

Overrides:

remove in class TransformedList<E,List<E>>

Parameters:

index - the index of the element to removed.

Returns:

the element previously at the specified position.

set

public List<E> set(int index,
                   List<E> value)

Replaces the element at the specified position in this list with the specified element (optional operation).

Specified by:

set in interface List<List<E>>

Overrides:

set in class TransformedList<E,List<E>>

Parameters:

index - index of element to replace.

value - element to be stored at the specified position.

Returns:

the element previously at the specified position.

add

public void add(int index,
                List<E> value)

This version of add will distribute all elements within the given value List into groups. Existing groups will be reused and new groups will be created as needed. As such, the index argument is meaningless.

Warning: This method breaks the contract required by List.add(int, Object).

Specified by:

add in interface List<List<E>>

Overrides:

add in class TransformedList<E,List<E>>

Parameters:

index - index at which the specified element is to be inserted.

value - element to be inserted.

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<List<E>>

Specified by:

size in interface List<List<E>>

Overrides:

size in class TransformedList<E,List<E>>

Returns:

the number of elements in this 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<List<E>>

Overrides:

dispose in class TransformedList<E,List<E>>