ca.odell.glazedlists
Class GlazedLists

java.lang.Object
  ca.odell.glazedlists.GlazedLists

public final class GlazedLists
extends Object

A factory for creating all sorts of objects to be used with Glazed Lists.

Author:

Jesse Wilson

Method Summary

static <E> ObservableElementList.Connector<E>	beanConnector(Class<E> beanClass) Create a new Connector for the ObservableElementList that works with JavaBeans' PropertyChangeListener.
static <E> ObservableElementList.Connector<E>	beanConnector(Class<E> beanClass, String addListener, String removeListener) Create a new Connector for the ObservableElementList that works with JavaBeans' PropertyChangeListener.
static <T> Comparator<T>	beanPropertyComparator(Class<T> className, String property) Creates a Comparator that uses Reflection to compare two instances of the specified Class by the given JavaBean property.
static <T> Comparator<T>	beanPropertyComparator(Class<T> className, String property, Comparator propertyComparator) Creates a Comparator that uses Reflection to compare two instances of the specified Class by the given JavaBean property.
static <E> Matcher<E>	beanPropertyMatcher(Class<E> beanClass, String propertyName, Object value) Create a new Matcher which uses reflection to read properties with the given propertyName from instances of the given beanClass and compare them with the given value.
static Comparator<Boolean>	booleanComparator() Creates a Comparator for use with Boolean objects.
static Comparator<String>	caseInsensitiveComparator() Creates a Comparator that compares String objects in a case-insensitive way.
static <T> Comparator<T>	chainComparators(List<Comparator<T>> comparators) Creates a chain of Comparators that applies the provided Comparators in the sequence specified until differences or absoulute equality.is determined.
static Comparator<Comparable>	comparableComparator() Creates a Comparator that compares Comparable objects.
static <E> EventList<E>	eventList(Collection<? extends E> contents) Creates a new EventList which contains the contents of the specified Collection.
static <E> MatcherEditor<E>	fixedMatcherEditor(Matcher<E> matcher) Get a MatcherEditor that is fixed on the specified Matcher.
static <E> CollectionList.Model<List<E>,E>	listCollectionListModel() Creates a CollectionList.Model that where Lists or EventLists are the elements of a parent EventList.
static <E> TransformedList<E,E>	readOnlyList(EventList<E> source) Wraps the source in an EventList that does not allow writing operations.
static <E> void	replaceAll(EventList<E> target, List<E> source, boolean updates) Replace the complete contents of the target EventList with the complete contents of the source EventList while making as few list changes as possible.
static <E> void	replaceAll(EventList<E> target, List<E> source, boolean updates, Comparator<E> comparator) Overloaded version of replaceAll(EventList,List,boolean) that uses a Comparator to determine equality rather than equals().
static Comparator<Comparable>	reverseComparator() Creates a reverse Comparator that works for Comparable objects.
static <T> Comparator<T>	reverseComparator(Comparator<T> forward) Creates a reverse Comparator that inverts the given Comparator.
static <E> ListEventListener<E>	syncEventListToList(EventList<E> source, List<E> target) Synchronize the specified EventList to the specified List.
static <T> TableFormat<T>	tableFormat(Class<T> baseClass, String[] propertyNames, String[] columnLabels) Creates a TableFormat that binds JavaBean properties to table columns via Reflection.
static <T> TableFormat<T>	tableFormat(Class<T> baseClass, String[] propertyNames, String[] columnLabels, boolean[] editable) Creates a TableFormat that binds JavaBean properties to table columns via Reflection.
static <T> TableFormat<T>	tableFormat(String[] propertyNames, String[] columnLabels) Creates a TableFormat that binds JavaBean properties to table columns via Reflection.
static <T> TableFormat<T>	tableFormat(String[] propertyNames, String[] columnLabels, boolean[] editable) Creates a TableFormat that binds JavaBean properties to table columns via Reflection.
static <E> TextFilterator<E>	textFilterator(String[] propertyNames) Creates a TextFilterator that searches the given JavaBean properties.
static <E> TransformedList<E,E>	threadSafeList(EventList<E> source) Wraps the source in an EventList that obtains a ReadWritLock for all operations.
static <E> ThresholdList.Evaluator<E>	thresholdEvaluator(String propertyName) Creates a ThresholdList.Evaluator that uses Reflection to utilize an integer JavaBean property as the threshold evaluation.
static TextFilterator	toStringTextFilterator() Creates a TextFilterator that searches against an Object's toString() value.
static <E> ListEventListener<E>	weakReferenceProxy(EventList<E> source, ListEventListener<E> target) Provides a proxy to another ListEventListener that may go out of scope without explicitly removing itself from the source list's set of listeners.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

replaceAll

public static <E> void replaceAll(EventList<E> target,
                                  List<E> source,
                                  boolean updates)

Replace the complete contents of the target EventList with the complete contents of the source EventList while making as few list changes as possible.

In a multi-threaded environment, it is necessary that the caller obtain the write lock for the target list before this method is invoked. If the source list is an EventList, its read lock must also be acquired.

This method shall be used when it is necessary to update an EventList to a newer state while minimizing the number of change events fired. It is desirable over clear(); addAll() because it will not cause selection to be lost if unnecessary. It is also useful where firing changes may be expensive, such as when they will cause writes to disk or the network.

This is implemented using Eugene W. Myer's paper, "An O(ND) Difference Algorithm and Its Variations", the same algorithm found in GNU diff.

Parameters:

updates - whether to fire update events for Objects that are equal in both Lists.

replaceAll

public static <E> void replaceAll(EventList<E> target,
                                  List<E> source,
                                  boolean updates,
                                  Comparator<E> comparator)

Overloaded version of replaceAll(EventList,List,boolean) that uses a Comparator to determine equality rather than equals().

Parameters:

comparator - the Comparator to determine equality between elements. This Comparator must return 0 for elements that are equal and nonzero for elements that are not equal. Sort order is not used.

beanPropertyComparator

public static <T> Comparator<T> beanPropertyComparator(Class<T> className,
                                                       String property)

Creates a Comparator that uses Reflection to compare two instances of the specified Class by the given JavaBean property. The JavaBean property must implement Comparable.

beanPropertyComparator

public static <T> Comparator<T> beanPropertyComparator(Class<T> className,
                                                       String property,
                                                       Comparator propertyComparator)

Creates a Comparator that uses Reflection to compare two instances of the specified Class by the given JavaBean property. The JavaBean property is compared using the provided Comparator.

booleanComparator

public static Comparator<Boolean> booleanComparator()

Creates a Comparator for use with Boolean objects.

caseInsensitiveComparator

public static Comparator<String> caseInsensitiveComparator()

Creates a Comparator that compares String objects in a case-insensitive way. This Comparator is equivalent to using String.CASE_INSENSITIVE_ORDER and exists here for convenience.

chainComparators

public static <T> Comparator<T> chainComparators(List<Comparator<T>> comparators)

Creates a chain of Comparators that applies the provided Comparators in the sequence specified until differences or absoulute equality.is determined.

comparableComparator

public static Comparator<Comparable> comparableComparator()

Creates a Comparator that compares Comparable objects.

reverseComparator

public static Comparator<Comparable> reverseComparator()

Creates a reverse Comparator that works for Comparable objects.

reverseComparator

public static <T> Comparator<T> reverseComparator(Comparator<T> forward)

Creates a reverse Comparator that inverts the given Comparator.

tableFormat

public static <T> TableFormat<T> tableFormat(String[] propertyNames,
                                             String[] columnLabels)

Creates a TableFormat that binds JavaBean properties to table columns via Reflection.

tableFormat

public static <T> TableFormat<T> tableFormat(Class<T> baseClass,
                                             String[] propertyNames,
                                             String[] columnLabels)

Creates a TableFormat that binds JavaBean properties to table columns via Reflection.

Parameters:

baseClass - the class of the Object to divide into columns. If specified, the returned class will provide implementation of AdvancedTableFormat.getColumnClass(int) and AdvancedTableFormat.getColumnComparator(int) by examining the classes of the column value.

tableFormat

public static <T> TableFormat<T> tableFormat(String[] propertyNames,
                                             String[] columnLabels,
                                             boolean[] editable)

Creates a TableFormat that binds JavaBean properties to table columns via Reflection. The returned TableFormat implements WritableTableFormat and may be used for an editable table.

tableFormat

public static <T> TableFormat<T> tableFormat(Class<T> baseClass,
                                             String[] propertyNames,
                                             String[] columnLabels,
                                             boolean[] editable)

Creates a TableFormat that binds JavaBean properties to table columns via Reflection. The returned TableFormat implements WritableTableFormat and may be used for an editable table.

Parameters:

baseClass - the class of the Object to divide into columns. If specified, the returned class will provide implementation of AdvancedTableFormat.getColumnClass(int) and AdvancedTableFormat.getColumnComparator(int) by examining the classes of the column value.

textFilterator

public static <E> TextFilterator<E> textFilterator(String[] propertyNames)

Creates a TextFilterator that searches the given JavaBean properties.

toStringTextFilterator

public static TextFilterator toStringTextFilterator()

Creates a TextFilterator that searches against an Object's toString() value.

thresholdEvaluator

public static <E> ThresholdList.Evaluator<E> thresholdEvaluator(String propertyName)

Creates a ThresholdList.Evaluator that uses Reflection to utilize an integer JavaBean property as the threshold evaluation.

listCollectionListModel

public static <E> CollectionList.Model<List<E>,E> listCollectionListModel()

Creates a CollectionList.Model that where Lists or EventLists are the elements of a parent EventList. This can be used to compose EventLists from other EventLists.

eventList

public static <E> EventList<E> eventList(Collection<? extends E> contents)

Creates a new EventList which contains the contents of the specified Collection. The EventList's order will be determined by contents.iterator().

readOnlyList

public static <E> TransformedList<E,E> readOnlyList(EventList<E> source)

Wraps the source in an EventList that does not allow writing operations.

The returned EventList is useful for programming defensively. A EventList is useful to supply an unknown class read-only access to your EventList.

The returned EventList will provides an up-to-date view of its source EventList so changes to the source EventList will still be reflected. For a static copy of any EventList it is necessary to copy the contents of that EventList into an ArrayList.

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

threadSafeList

public static <E> TransformedList<E,E> threadSafeList(EventList<E> source)

Wraps the source in an EventList that obtains a ReadWritLock for all operations.

This provides some support for sharing EventLists between multiple threads.

Using a ThreadSafeList for concurrent access to lists can be expensive because a ReadWriteLock is aquired and released for every operation.

Warning: Although this class provides thread safe access, it does not provide any guarantees that changes will not happen between method calls. For example, the following code is unsafe because the source EventList may change between calls to size() and get():

 EventList source = ...
 ThreadSafeList myList = new ThreadSafeList(source);
 if(myList.size() > 3) {
   System.out.println(myList.get(3));
 }

Warning: The objects returned by iterator(), subList(), etc. are not thread safe.

See Also:

ca.odell.glazedlists.util.concurrent

weakReferenceProxy

public static <E> ListEventListener<E> weakReferenceProxy(EventList<E> source,
                                                          ListEventListener<E> target)

Provides a proxy to another ListEventListener that may go out of scope without explicitly removing itself from the source list's set of listeners.

This exists to solve a garbage collection problem. Suppose I have an EventList L and I request a ListIterator for L. The ListIterator must listen for change events to L in order to be consistent. Therefore such an iterator will register itself as a listener for L. When the iterator goes out of scope (as they usually do), it will remain as a listener for L. This prevents the iterator object from ever being garbage collected! But the iterator is never used again. Because iterators can be used very frequently, this will cause an unacceptable memory leak.

Instead of adding the iterator directly as a listener for L, add the proxy instead. The proxy will retain a WeakReference to the iterator and forward events to the iterator as long as it is reachable. When theiterator is no longer reachable, the proxy will remove itself from the list of listeners for L. All garbage is then available for collection.

See Also:

WeakReference

beanConnector

public static <E> ObservableElementList.Connector<E> beanConnector(Class<E> beanClass)

Create a new Connector for the ObservableElementList that works with JavaBeans' PropertyChangeListener. The methods to add and remove listeners are detected automatically by examining the bean class and searching for a method prefixed with "add" or "remove" taking a single PropertyChangeListener argument.

Parameters:

beanClass - a class with both addPropertyChangeListener(PropertyChangeListener) and removePropertyChangeListener(PropertyChangeListener), or similar methods.

Returns:

an ObservableElementList.Connector for the specified class

beanConnector

public static <E> ObservableElementList.Connector<E> beanConnector(Class<E> beanClass,
                                                                   String addListener,
                                                                   String removeListener)

Create a new Connector for the ObservableElementList that works with JavaBeans' PropertyChangeListener. The methods to add and remove listeners are specified by name. Such methods must take a single PropertyChangeListener argument.

Parameters:

beanClass - a class with both methods as specified.

addListener - a method name such as "addPropertyChangeListener"

removeListener - a method name such as "removePropertyChangeListener"

Returns:

an ObservableElementList.Connector for the specified class

beanPropertyMatcher

public static <E> Matcher<E> beanPropertyMatcher(Class<E> beanClass,
                                                 String propertyName,
                                                 Object value)

Create a new Matcher which uses reflection to read properties with the given propertyName from instances of the given beanClass and compare them with the given value.

Parameters:

beanClass - the type of class containing the named bean property

propertyName - the name of the bean property

value - the value to compare with the bean property

Returns:

true if the named bean property equals the given value

fixedMatcherEditor

public static <E> MatcherEditor<E> fixedMatcherEditor(Matcher<E> matcher)

Get a MatcherEditor that is fixed on the specified Matcher.

syncEventListToList

public static <E> ListEventListener<E> syncEventListToList(EventList<E> source,
                                                           List<E> target)

Synchronize the specified EventList to the specified List. Each time the EventList is changed, the changes are applied to the List as well, so that the two lists are always equal.

This is useful when a you need to support a List datamodel but would prefer to manipulate that List with the convenience of EventLists:

List someList = ...

 // create an EventList with the contents of someList
 EventList eventList = GlazedLists.eventList(someList);

 // propagate changes from eventList to someList
 GlazedLists.syncEventListToList(eventList, someList);

 // test it out, should print "true, true, true true"
 eventList.add("boston creme");
 System.out.println(eventList.equals(someList));
 eventList.add("crueller");
 System.out.println(eventList.equals(someList));
 eventList.remove("bostom creme");
 System.out.println(eventList.equals(someList));
 eventList.clear();
 System.out.println(eventList.equals(someList));

Parameters:

source - the EventList which provides the master view. Each change to this EventList will be applied to the List.

target - the List to host a copy of the EventList. This List should not be changed after the lists have been synchronized. Otherwise a RuntimeException will be thrown when the drift is detected. This class must support all mutating List operations.

Returns:

the ListEventListener providing the link from the source EventList to the target List. To stop the synchronization, use EventList.removeListEventListener(ListEventListener).