CollectionList.Model,E> listCollectionListModel
public static CollectionList.Model,E> listCollectionListModel()
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);
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 Comparator
s that applies the provided
Comparator
s in the sequence specified until differences or
absolute equality is determined.
Comparator chainComparators
public static Comparator chainComparators(List> comparators)
Creates a chain of Comparator
s that applies the provided
Comparator
s 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)
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)
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
EventList
s:
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));
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.
- 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
EventList
s during
software development and testing phases.
source
- the EventList
on which to provide type safetytypes
- 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
- 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.
java.lang.ref.WeakReference
Matcher beanPropertyMatcher
public static Matcher beanPropertyMatcher(Class beanClass,
String propertyName,
Object value)
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
.
beanClass
- the type of class containing the named bean propertypropertyName
- the name of the bean propertyvalue
- the value to compare with the bean property
- true if the named bean property equals the given
value
MatcherEditor fixedMatcherEditor
public static MatcherEditor fixedMatcherEditor(Matcher 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.
beanClass
- a class with both addPropertyChangeListener(PropertyChangeListener)
and removePropertyChangeListener(PropertyChangeListener)
,
or similar methods.
- 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.PropertyChangeEvent
s.
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[])
beanClass
- a class with both
addPropertyChangeListener(PropertyChangeListener)
and
removePropertyChangeListener(PropertyChangeListener)
, or similar
methods.eventMatcher
- for matching PropertyChangeEvents that will be delivered to the
ObservableElementList
- 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.
beanClass
- a class with both methods as specified.addListener
- a method name such as "addPropertyChangeListener"removeListener
- a method name such as "removePropertyChangeListener"
- 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.PropertyChangeEvent
s.
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[])
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
- 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.PropertyChangeEvent
s
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.PropertyChangeEvent
s
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.
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 thempropertyNames
- specifies the properties by name whose java.beans.PropertyChangeEvent
s
should be matched or filtered
- 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.
TableFormat tableFormat
public static TableFormat tableFormat(Class baseClass,
String[] propertyNames,
String[] columnLabels,
boolean[] editable)
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)
TextFilterator textFilterator
public static TextFilterator textFilterator(Class beanClass,
String... propertyNames)
TextFilterator textFilterator
public static TextFilterator textFilterator(String... propertyNames)
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
EventList
s 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.
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.
source
- the EventList
which provides the master view.
Each change to this EventList
will be applied to the
MultiMapkeyMaker
- 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
- 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
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.
- 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.
source
- the EventList
which provides the master view.
Each change to this EventList
will be applied to the
MultiMapkeyMaker
- the FunctionList.Function
which produces a key
for each value in the source
. It is imperative that the
keyMaker produce immutable objects.
- 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.
- 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.
updates
- whether to fire update events for Objects that are equal in
both List
s.
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()
.
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.
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 List
s.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
.
Collections.sort
, SortedSet