ca.odell.glazedlists

Class GlazedLists


public final class GlazedLists
extends java.lang.Object

A factory for creating all sorts of objects to be used with Glazed Lists.
Author:
Jesse Wilson

Method Summary

static
CollectionList.Model,E> listCollectionListModel()
Creates a CollectionList.Model that where Lists or EventLists are the elements of a parent EventList.
static
Comparator beanPropertyComparator(Class 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
Comparator beanPropertyComparator(Class clazz, String property, String... properties)
Creates a Comparator that uses Reflection to compare two instances of the specified Class by the given JavaBean properties.
static
Comparator chainComparators(Comparator... comparators)
Creates a chain of Comparators that applies the provided Comparators in the sequence specified until differences or absolute equality is determined.
static
Comparator chainComparators(List> comparators)
Creates a chain of Comparators that applies the provided Comparators in the sequence specified until differences or absolute equality is determined.
static
Comparator reverseComparator(Comparator forward)
Creates a reverse Comparator that inverts the given Comparator.
static
EventList eventList(E> contents)
Creates a new EventList which contains the contents of the specified Collection.
static
EventList eventListOf(E... contents)
Creates a new EventList which contains the given elements.
static
Filterator filterator(Class beanClass, String... propertyNames)
Creates a TextFilterator that searches the given JavaBean properties of the specified class.
static
Filterator filterator(String... propertyNames)
Creates a TextFilterator that searches the given JavaBean properties.
static
FunctionList.Function toStringFunction(Class beanClass, String propertyName)
Get a FunctionList.Function that extracts the property with the given propertyName from objects of the given beanClass and then formats the return value as a String.
static
FunctionList.Function beanFunction(Class beanClass, String propertyName)
Get a FunctionList.Function that extracts the property with the given propertyName from objects of the given beanClass.
static
FunctionList.Function constantFunction(V value)
Get a FunctionList.Function that always returns the given value, regardless of its input.
static
ListEventListener syncEventListToList(EventList source, List target)
Synchronize the specified EventList to the specified List.
static
ListEventListener typeSafetyListener(EventList source, Set types)
Check list elements for type safety after they are added to an EventList using a ListEventListener.
static
ListEventListener weakReferenceProxy(EventList source, ListEventListener 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.
static
Matcher beanPropertyMatcher(Class beanClass, String propertyName, Object value)
Deprecated. as of 3/3/2006 - this method has been replaced by Matchers.
static
MatcherEditor fixedMatcherEditor(Matcher matcher)
Get a MatcherEditor that is fixed on the specified Matcher.
static
ObservableElementList.Connector beanConnector(Class beanClass)
Create a new Connector for the ObservableElementList that works with JavaBeans' java.beans.PropertyChangeListener.
static
ObservableElementList.Connector beanConnector(Class beanClass, Matcher eventMatcher)
Create a new Connector for the ObservableElementList that works with JavaBeans' java.beans.PropertyChangeListener.
static
ObservableElementList.Connector beanConnector(Class beanClass, String addListener, String removeListener)
Create a new Connector for the ObservableElementList that works with JavaBeans' java.beans.PropertyChangeListener.
static
ObservableElementList.Connector beanConnector(Class beanClass, String addListener, String removeListener, Matcher eventMatcher)
Create a new Connector for the ObservableElementList that works with JavaBeans' java.beans.PropertyChangeListener.
static
ObservableElementList.Connector beanConnector(Class beanClass, boolean matchPropertyNames, String... propertyNames)
Create a new Connector for the ObservableElementList that works with JavaBeans' java.beans.PropertyChangeListener.
static
TableFormat tableFormat(Class baseClass, String[] propertyNames, String[] columnLabels)
Creates a TableFormat that binds JavaBean properties to table columns via Reflection.
static
TableFormat tableFormat(Class baseClass, String[] propertyNames, String[] columnLabels, boolean[] editable)
Creates a TableFormat that binds JavaBean properties to table columns via Reflection.
static
TableFormat tableFormat(String[] propertyNames, String[] columnLabels)
Creates a TableFormat that binds JavaBean properties to table columns via Reflection.
static
TableFormat tableFormat(String[] propertyNames, String[] columnLabels, boolean[] editable)
Creates a TableFormat that binds JavaBean properties to table columns via Reflection.
static
TextFilterator textFilterator(Class beanClass, String... propertyNames)
Creates a TextFilterator that searches the given JavaBean properties.
static
TextFilterator textFilterator(String... propertyNames)
Creates a TextFilterator that searches the given JavaBean properties.
static
TextFilterator toStringTextFilterator()
Creates a TextFilterator that searches against an Object's toString() value.
static
ThresholdList.Evaluator thresholdEvaluator(String propertyName)
Creates a ThresholdList.Evaluator that uses Reflection to utilize an integer JavaBean property as the threshold evaluation.
static
TransformedList readOnlyList(EventList source)
Wraps the source in an EventList that does not allow writing operations.
static
TransformedList threadSafeList(EventList source)
Wraps the source in an EventList that obtains a ReadWritLock for all operations.
static
V> DisposableMap> syncEventListToMultiMap(EventList source, ca.odell.glazedlists.FunctionList.Function keyMaker, K> keyGrouper)
Synchronize the specified EventList to a MultiMap that is returned from this method.
static
V> DisposableMap syncEventListToMap(EventList source, ca.odell.glazedlists.FunctionList.Function keyMaker)
Synchronize the specified EventList to a Map that is returned from this method.
static Comparator
booleanComparator()
Creates a Comparator for use with Boolean objects.
static Comparator
caseInsensitiveComparator()
Creates a Comparator that compares String objects in a case-insensitive way.
static
extends Comparable, V> DisposableMap> syncEventListToMultiMap(EventList source, ca.odell.glazedlists.FunctionList.Function keyMaker)
Synchronize the specified EventList to a MultiMap that is returned from this method.
static
extends Comparable> Comparator comparableComparator()
Creates a Comparator that compares Comparable objects.
static
extends Comparable> Comparator reverseComparator()
Creates a reverse Comparator that works for Comparable objects.
static
extends Observable> ObservableElementList.Connector observableConnector()
Create a new Connector for the ObservableElementList that works with subclasses of the archaic Observable base class.
static
void replaceAll(EventList target, List 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
void replaceAll(EventList target, List source, boolean updates, Comparator comparator)
Overloaded version of replaceAll(EventList,List,boolean) that uses a Comparator to determine equality rather than equals().
static
void replaceAllSorted(EventList target, Collection source, boolean updates, Comparator comparator)
Replace the complete contents of the target EventList with the complete contents of the source Collection while making as few list changes as possible.

Method Details

CollectionList.Model,E> listCollectionListModel

public static  CollectionList.Model,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.

Comparator beanPropertyComparator

public static  Comparator beanPropertyComparator(Class 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.

Comparator beanPropertyComparator

public static  Comparator beanPropertyComparator(Class clazz,
                                                       String property,
                                                       String... properties)
Creates a Comparator that uses Reflection to compare two instances of the specified Class by the given JavaBean properties. The JavaBean property and any extra properties must implement Comparable.

The following example code sorts a List of Customers by first name, with ties broken by last name.

    List customers = ...
    Comparator comparator = GlazedLists.beanPropertyComparator(Customer.class, "firstName", "lastName");
    Collections.sort(customers, comparator);
 
Parameters:
clazz - the name of the class which defines the accessor method for the given property and optionaly properties
property - the name of the first Comparable property to be extracted and used to compare instances of the clazz
properties - the name of optional Comparable properties, each of which is used to break ties for the prior property.

Comparator chainComparators

public static  Comparator chainComparators(Comparator... comparators)
Creates a chain of Comparators that applies the provided Comparators in the sequence specified until differences or absolute equality is determined.

Comparator chainComparators

public static  Comparator chainComparators(List> comparators)
Creates a chain of Comparators that applies the provided Comparators in the sequence specified until differences or absolute equality is determined.

Comparator reverseComparator

public static  Comparator reverseComparator(Comparator forward)
Creates a reverse Comparator that inverts the given Comparator.

EventList eventList

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

EventList eventListOf

public static  EventList eventListOf(E... contents)
Creates a new EventList which contains the given elements.

Filterator filterator

public static  Filterator filterator(Class beanClass,
                                               String... propertyNames)
Creates a TextFilterator that searches the given JavaBean properties of the specified class.

Filterator filterator

public static  Filterator filterator(String... propertyNames)
Creates a TextFilterator that searches the given JavaBean properties.

FunctionList.Function toStringFunction

public static  FunctionList.Function toStringFunction(Class beanClass,
                                                                   String propertyName)
Get a FunctionList.Function that extracts the property with the given propertyName from objects of the given beanClass and then formats the return value as a String.

FunctionList.Function beanFunction

public static  FunctionList.Function beanFunction(Class beanClass,
                                                            String propertyName)
Get a FunctionList.Function that extracts the property with the given propertyName from objects of the given beanClass.

FunctionList.Function constantFunction

public static  FunctionList.Function constantFunction(V value)
Get a FunctionList.Function that always returns the given value, regardless of its input.

ListEventListener syncEventListToList

public static  ListEventListener syncEventListToList(EventList source,
                                                           List 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).

ListEventListener typeSafetyListener

public static  ListEventListener typeSafetyListener(EventList source,
                                                          Set types)
Check list elements for type safety after they are added to an EventList using a ListEventListener. The ListEventListener which is installed and returned to the caller (which they may uninstall at their leisure) will throw an IllegalArgumentException if it detects the addition of an element with an unsupported type.

This ListEventListener is typically used as a tool to check invariants of the elements of EventLists during software development and testing phases.

Parameters:
source - the EventList on which to provide type safety
types - the set of types to which each list element must be assignable - note null is an acceptable type and indicates the EventList expects to contain null elements
Returns:
the ListEventListener providing the which provides type safety checking on the given source. To stop the type safety checking, use EventList.removeListEventListener(ListEventListener).

ListEventListener weakReferenceProxy

public static  ListEventListener weakReferenceProxy(EventList source,
                                                          ListEventListener 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 obtain 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 of L. This prevents the iterator object from ever being garbage collected, though the iterator can never be 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 a proxy instead. The proxy will retain a WeakReference to the iterator and forward events to the iterator as long as it is reachable. When the iterator 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:
java.lang.ref.WeakReference

Matcher beanPropertyMatcher

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

Deprecated. as of 3/3/2006 - this method has been replaced by Matchers. Matchers is now the permanent factory class which creates all basic Matcher implementations.

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

MatcherEditor fixedMatcherEditor

public static  MatcherEditor fixedMatcherEditor(Matcher matcher)
Get a MatcherEditor that is fixed on the specified Matcher.

ObservableElementList.Connector beanConnector

public static  ObservableElementList.Connector beanConnector(Class beanClass)
Create a new Connector for the ObservableElementList that works with JavaBeans' java.beans.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 java.beans.PropertyChangeListener argument.
Parameters:
beanClass - a class with both addPropertyChangeListener(PropertyChangeListener) and removePropertyChangeListener(PropertyChangeListener), or similar methods.
Returns:
an ObservableElementList.Connector for the specified class

ObservableElementList.Connector beanConnector

public static  ObservableElementList.Connector beanConnector(Class beanClass,
                                                                   Matcher eventMatcher)
Create a new Connector for the ObservableElementList that works with JavaBeans' java.beans.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 java.beans.PropertyChangeListener argument.

The event matcher allows filtering of java.beans.PropertyChangeEvents. Only matching events are delivered to the ObservableElementList. To create a matcher that matches PropertyChangeEvents by property names, you can use Matchers.propertyEventNameMatcher(boolean, String[])

Parameters:
beanClass - a class with both addPropertyChangeListener(PropertyChangeListener) and removePropertyChangeListener(PropertyChangeListener), or similar methods.
eventMatcher - for matching PropertyChangeEvents that will be delivered to the ObservableElementList
Returns:
an ObservableElementList.Connector for the specified class

ObservableElementList.Connector beanConnector

public static  ObservableElementList.Connector beanConnector(Class beanClass,
                                                                   String addListener,
                                                                   String removeListener)
Create a new Connector for the ObservableElementList that works with JavaBeans' java.beans.PropertyChangeListener. The methods to add and remove listeners are specified by name. Such methods must take a single java.beans.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

ObservableElementList.Connector beanConnector

public static  ObservableElementList.Connector beanConnector(Class beanClass,
                                                                   String addListener,
                                                                   String removeListener,
                                                                   Matcher eventMatcher)
Create a new Connector for the ObservableElementList that works with JavaBeans' java.beans.PropertyChangeListener. The methods to add and remove listeners are specified by name. Such methods must take a single java.beans.PropertyChangeListener argument.

The event matcher allows filtering of java.beans.PropertyChangeEvents. Only matching events are delivered to the ObservableElementList. To create a matcher that matches PropertyChangeEvents by property names, you can use Matchers.propertyEventNameMatcher(boolean, String[])

Parameters:
beanClass - a class with both methods as specified.
addListener - a method name such as "addPropertyChangeListener"
removeListener - a method name such as "removePropertyChangeListener"
eventMatcher - for matching PropertyChangeEvents that will be delivered to the ObservableElementList
Returns:
an ObservableElementList.Connector for the specified class

ObservableElementList.Connector beanConnector

public static  ObservableElementList.Connector beanConnector(Class beanClass,
                                                                   boolean matchPropertyNames,
                                                                   String... propertyNames)
Create a new Connector for the ObservableElementList that works with JavaBeans' java.beans.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 java.beans.PropertyChangeListener argument.

Use this variant, if you want to control which java.beans.PropertyChangeEvents are delivered to the ObservableElementList. You can match or filter events by name.

If matchPropertyNames is true, the propertyNames parameter specifies the set of properties by name whose java.beans.PropertyChangeEvents should be delivered to the ObservableElementList, e.g. property change events for properties not contained in the specified propertyNames are ignored in this case. If matchPropertyNames is false, then the specified propertyNames are filtered, e.g. all but the specified property change events are delivered to the ObservableElementList.

Parameters:
beanClass - a class with both addPropertyChangeListener(PropertyChangeListener) and removePropertyChangeListener(PropertyChangeListener), or similar methods.
matchPropertyNames - if true, match property change events against the specified property names, if false filter them
propertyNames - specifies the properties by name whose java.beans.PropertyChangeEvents should be matched or filtered
Returns:
an ObservableElementList.Connector for the specified class

TableFormat tableFormat

public static  TableFormat tableFormat(Class 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 tableFormat

public static  TableFormat tableFormat(Class 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.

TableFormat tableFormat

public static  TableFormat tableFormat(String[] propertyNames,
                                             String[] columnLabels)
Creates a TableFormat that binds JavaBean properties to table columns via Reflection.

TableFormat tableFormat

public static  TableFormat 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.

TextFilterator textFilterator

public static  TextFilterator textFilterator(Class beanClass,
                                                   String... propertyNames)
Creates a TextFilterator that searches the given JavaBean properties.

TextFilterator textFilterator

public static  TextFilterator textFilterator(String... propertyNames)
Creates a TextFilterator that searches the given JavaBean properties.

TextFilterator toStringTextFilterator

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

ThresholdList.Evaluator thresholdEvaluator

public static  ThresholdList.Evaluator thresholdEvaluator(String propertyName)
Creates a ThresholdList.Evaluator that uses Reflection to utilize an integer JavaBean property as the threshold evaluation.

TransformedList readOnlyList

public static  TransformedList readOnlyList(EventList 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.


TransformedList threadSafeList

public static  TransformedList threadSafeList(EventList 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

V> DisposableMap> syncEventListToMultiMap

public static  DisposableMap> syncEventListToMultiMap(EventList source,
                                                                       ca.odell.glazedlists.FunctionList.Function keyMaker,
                                                                       K> keyGrouper)
Synchronize the specified EventList to a MultiMap that is returned from this method. Each time the EventList is changed the MultiMap is updated to reflect the change.

This can be useful when it is known that an EventList will experience very few mutations compared to read operation and wants to provide a data structure that guarantees fast O(1) reads.

The keys of the MultiMap are determined by evaluating each source element with the keyMaker function. This form of the MultiMap makes no assumptions about the keys of the MultiMap and relies on the given keyGrouper to define the grouping of values.

If two distinct values, say v1 and v2 each produce a common key, k, when they are evaluated by the keyMaker function, then a corresponding entry in the MultiMap will resemble:

k -> {v1, v2}

For example, assume the keyMaker function returns the first letter of a name and the source EventList contains the names:

{"Andy", "Arthur", "Jesse", "Holger", "James"}

The MultiMap returned by this method would thus resemble:

"A" -> {"Andy", "Arthur"}
"H" -> {"Holger"}
"J" -> {"Jesse", "James"}

It is important to note that all mutating methods on the Map interface "write through" to the backing EventList as expected. These mutating methods include:

  • the mutating methods of Map.keySet() and its Iterator
  • the mutating methods of Map.values() and its Iterator
  • the mutating methods of Map.entrySet() and its Iterator
  • the Map.Entry.setValue method
  • the mutating methods of Map itself, including Map.put, Map.putAll, Map.remove, and Map.clear
For information on MultiMaps go here.
Parameters:
source - the EventList which provides the master view. Each change to this EventList will be applied to the MultiMap
keyMaker - the FunctionList.Function which produces a key for each value in the source. It is imperative that the keyMaker produce immutable objects.
keyGrouper - the Comparator which groups together values that share common keys
Returns:
a MultiMap which remains in sync with changes that occur to the underlying source EventList

V> DisposableMap syncEventListToMap

public static  DisposableMap syncEventListToMap(EventList source,
                                                            ca.odell.glazedlists.FunctionList.Function keyMaker)
Synchronize the specified EventList to a Map that is returned from this method. Each time the EventList is changed the Map is updated to reflect the change.

This can be useful when it is known that an EventList will experience very few mutations compared to read operation and wants to provide a data structure that guarantees fast O(1) reads.

The keys of the Map are determined by evaluating each source element with the keyMaker function. The Map implementation assumes that each value has a unique key, and verifies this invariant at runtime, throwing a RuntimeException if it is ever violated. For example, if two distinct values, say v1 and v2 each produce the key k when they are evaluated by the keyMaker function, an IllegalStateException is thrown to proactively indicate the error.

As for example of normal usage, assume the keyMaker function returns the first letter of a name and the source EventList contains the names:

{"Kevin", "Jesse", "Holger"}

The Map returned by this method would thus resemble:

"K" -> "Kevin"
"J" -> "Jesse"
"H" -> "Holger"

It is important to note that all mutating methods on the Map interface "write through" to the backing EventList as expected. These mutating methods include:

  • the mutating methods of Map.keySet() and its Iterator
  • the mutating methods of Map.values() and its Iterator
  • the mutating methods of Map.entrySet() and its Iterator
  • the Map.Entry.setValue method
Parameters:
source - the EventList which provides the values of the map. Each change to this EventList will be applied to the Map.
keyMaker - the FunctionList.Function which produces a key for each value in the source. It is imperative that the keyMaker produce immutable objects.
Returns:
a Map which remains in sync with changes that occur to the underlying source EventList

booleanComparator

public static Comparator booleanComparator()
Creates a Comparator for use with Boolean objects.

caseInsensitiveComparator

public static Comparator 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.

extends Comparable, V> DisposableMap> syncEventListToMultiMap

public static  DisposableMap> syncEventListToMultiMap(EventList source,
                                                                                          ca.odell.glazedlists.FunctionList.Function keyMaker)
Synchronize the specified EventList to a MultiMap that is returned from this method. Each time the EventList is changed the MultiMap is updated to reflect the change.

This can be useful when it is known that an EventList will experience very few mutations compared to read operation and wants to provide a data structure that guarantees fast O(1) reads.

The keys of the MultiMap are determined by evaluating each source element with the keyMaker function. This form of the MultiMap requires that the keys produced by the keyMaker are Comparable and that the natural ordering of those keys also defines the grouping of values. If either of those assumptions are false, consider using syncEventListToMultiMap(EventList, FunctionList.Function, Comparator).

If two distinct values, say v1 and v2 each produce a common key, k, when they are evaluated by the keyMaker function, then a corresponding entry in the MultiMap will resemble:

k -> {v1, v2}

For example, assume the keyMaker function returns the first letter of a name and the source EventList contains the names:

{"Andy", "Arthur", "Jesse", "Holger", "James"}

The MultiMap returned by this method would thus resemble:

"A" -> {"Andy", "Arthur"}
"H" -> {"Holger"}
"J" -> {"Jesse", "James"}

It is important to note that all mutating methods on the Map interface "write through" to the backing EventList as expected. These mutating methods include:

  • the mutating methods of Map.keySet() and its Iterator
  • the mutating methods of Map.values() and its Iterator
  • the mutating methods of Map.entrySet() and its Iterator
  • the Map.Entry.setValue method
  • the mutating methods of Map itself, including Map.put, Map.putAll, Map.remove, and Map.clear
For information on MultiMaps go here.
Parameters:
source - the EventList which provides the master view. Each change to this EventList will be applied to the MultiMap
keyMaker - the FunctionList.Function which produces a key for each value in the source. It is imperative that the keyMaker produce immutable objects.
Returns:
a MultiMap which remains in sync with changes that occur to the underlying source EventList

extends Comparable> Comparator comparableComparator

public static  Comparator comparableComparator()
Creates a Comparator that compares Comparable objects.

extends Comparable> Comparator reverseComparator

public static  Comparator reverseComparator()
Creates a reverse Comparator that works for Comparable objects.

extends Observable> ObservableElementList.Connector observableConnector

public static  ObservableElementList.Connector observableConnector()
Create a new Connector for the ObservableElementList that works with subclasses of the archaic Observable base class. Each element of the ObservableElementList must extend the Observable base class.
Returns:
an ObservableElementList.Connector for objects that extend Observable

void replaceAll

public static  void replaceAll(EventList target,
                                  List 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.

Note that the runtime of this method is significantly less efficient in both time and memory than the sorted version of replaceAll.

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

void replaceAll

public static  void replaceAll(EventList target,
                                  List source,
                                  boolean updates,
                                  Comparator 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.

void replaceAllSorted

public static  void replaceAllSorted(EventList target,
                                        Collection source,
                                        boolean updates,
                                        Comparator comparator)
Replace the complete contents of the target EventList with the complete contents of the source Collection while making as few list changes as possible.

Unlike the general versions of this method, the sorted version requires that both the input and the output are sorted collections, and that they're sorted with the Comparator specified. If they're sorted in natural order, use comparableComparator().

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.

Note that this method is significantly more efficient in both time and memory than the general version of replaceAll.

Parameters:
target - an EventList sorted with the Comparator specified. Its contents will be replaced with those in source.
source - a collection sorted with the Comparator specified.
updates - whether to fire update events for Objects that are equal in both Lists.
comparator - defines the sort order for both target and source. It should also define identity. Ie, elements that compare to 0 by this comparator represent the same logical element in the list. If null, the comparableComparator will be used, which means that all elements must implement Comparable.
See Also:
Collections.sort, SortedSet

Glazed Lists, Copyright © 2003 publicobject.com, O'Dell Engineering.
Documentation build by pbuilder at 2009-07-14 22:05