com.levigo.util.base.glazedlists.matchers
Class Matchers

java.lang.Object
  com.levigo.util.base.glazedlists.matchers.Matchers

public final class Matchers
extends Object

A factory for creating Matchers.

Author:

Jesse Wilson

Method Summary

static <E> Matcher<E>	and(Matcher<? super E>... matchers) Returns a Matcher which returns a match when all of the given matchers report a match.
static <E> Matcher<E>	beanPropertyMatcher(Class<E> beanClass, String propertyName, Object expectedValue) Creates a Matcher that uses Reflection to compare the expectedValue of the specified property of an object to the expectedValue.
static <E> boolean	contains(Collection<E> collection, Matcher<? super E> matcher) Returns true if the given collection contains an element that satisfies the given matcher; false otherise.
static <E> int	count(Collection<E> collection, Matcher<? super E> matcher) Iterate through the specified collection and count all elements that match the specified matcher.
static <E> Matcher<E>	falseMatcher() Get a Matcher that always returns false, therefore matching nothing..
static <E> boolean	filter(Collection<E> collection, Matcher<? super E> matcher) Iterate through the specified collection and remove all elements that don't match the specified matcher.
static <E> int	indexOf(List<E> list, Matcher<? super E> matcher) Returns the index of the first element from the given list that satisfies the matcher or -1 if no such element exists.
static <E> Matcher<E>	invert(Matcher<E> original) Get a Matcher that returns the opposite of the specified Matcher.
static <E> Matcher<E>	isNotNull() Get a Matcher that returns returns true iff it is given a null object.
static <E> Matcher<E>	isNull() Get a Matcher that returns returns true iff it is given a non-null object.
static Matcher<String>	nonNullAndNonEmptyString() Get a Matcher that returns true iff it is given a non-null and non-empty String.
static <E> Matcher<E>	or(Matcher<? super E>... matchers) Returns a Matcher which returns a match when any of the given matchers reports a match.
static Matcher<PropertyChangeEvent>	propertyEventNameMatcher(boolean matchPropertyNames, String... propertyNames) Create a Matcher that uses the given propertyNames to match PropertyChangeEvents by their property name.
static <D extends Comparable,E> Matcher<E>	rangeMatcher(D start, D end) Creates a Matcher that matches Comparable objects for containment within the range between the given start and end.
static <D extends Comparable,E> Matcher<E>	rangeMatcher(D start, D end, Filterator<D,E> filterator) Creates a Matcher that uses the given filterator to extract Comparable objects from filtered objects and compares those Comparables against the range between the given start and end.
static <E> Collection<? super E>	select(Collection<E> collection, Matcher<? super E> matcher) Add all elements from the given collection that satisfy the matcher to a new ArrayList.
static <E> Collection<? super E>	select(Collection<E> collection, Matcher<? super E> matcher, Collection<? super E> results) Add all elements from the given collection that satisfy the matcher to the given results Collection.
static <E> E[]	select(E[] items, Matcher<? super E> matcher) Return a new array containing only the items that satisfy the matcher.
static <E> Matcher<E>	trueMatcher() Get a Matcher that always returns true, therefore matching everything.
static <E> Matcher<E>	types(Class... classes) Returns a Matcher which reports a match when the given object to match is not null and reports on of the given classes as its type.
static <E> MatcherEditor<E>	weakReferenceProxy(MatcherEditor<E> matcherEditor) Provides a proxy to another MatcherEditor that may go out of scope without explicitly removing itself from the source MatcherEditor's set of listeners.

Methods inherited from class java.lang.Object

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

Method Detail

weakReferenceProxy

public static <E> MatcherEditor<E> weakReferenceProxy(MatcherEditor<E> matcherEditor)

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

This exists to solve a garbage collection problem. Suppose I have a MatcherEditor M which is long lived and many MatcherEditor.Listeners, t which must listen to M while they exist. Instead of adding each of the t directly as listeners of M, add a proxy instead. The proxy will retain a WeakReference to the t, and will remove itself from the list of listeners for M.

The MatcherEditor returned by this method makes implementing the above scheme trivial. It does two things for you automatically:

1. It wraps each MatcherEditor.Listener passed to MatcherEditor.addMatcherEditorListener(com.levigo.util.base.glazedlists.matchers.MatcherEditor.Listener) in a WeakReference so that the listeners are garbage collected when they become unreachable.

2. It registers itself as a weak listener of the given matcherEditor so the MatcherEditor returned by this method will be garbage collected when it becomes unreachable.

See Also:

WeakReference

trueMatcher

public static <E> Matcher<E> trueMatcher()

Get a Matcher that always returns true, therefore matching everything.

falseMatcher

public static <E> Matcher<E> falseMatcher()

Get a Matcher that always returns false, therefore matching nothing..

invert

public static <E> Matcher<E> invert(Matcher<E> original)

Get a Matcher that returns the opposite of the specified Matcher.

isNull

public static <E> Matcher<E> isNull()

Get a Matcher that returns returns true iff it is given a non-null object.

isNotNull

public static <E> Matcher<E> isNotNull()

Get a Matcher that returns returns true iff it is given a null object.

nonNullAndNonEmptyString

public static Matcher<String> nonNullAndNonEmptyString()

Get a Matcher that returns true iff it is given a non-null and non-empty String.

beanPropertyMatcher

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

Creates a Matcher that uses Reflection to compare the expectedValue of the specified property of an object to the expectedValue.

rangeMatcher

public static <D extends Comparable,E> Matcher<E> rangeMatcher(D start,
                                                               D end)

Creates a Matcher that matches Comparable objects for containment within the range between the given start and end.

rangeMatcher

public static <D extends Comparable,E> Matcher<E> rangeMatcher(D start,
                                                               D end,
                                                               Filterator<D,E> filterator)

Creates a Matcher that uses the given filterator to extract Comparable objects from filtered objects and compares those Comparables against the range between the given start and end. If at least one Comparable returned by the filterator is within the range, the object is considered a match.

null start or end values are allowed and are interpreted as "no start" or "no end" to the range respectively.

Parameters:

start - the Comparable which starts the range

end - the Comparable which ends the range

filterator - the logic for extracting filter Comparables from filtered objects

propertyEventNameMatcher

public static Matcher<PropertyChangeEvent> propertyEventNameMatcher(boolean matchPropertyNames,
                                                                    String... propertyNames)

Create a Matcher that uses the given propertyNames to match PropertyChangeEvents by their property name. The concrete behaviour depends on the matchPropertyNames parameter. If you want to match property change events against a known set of property names, use a value of true. Alternatively, when you specify false, the specified property names will serve as an exclude list, e.g. if an event matches a specified property name, it will be filtered out.

These matchers are especially useful as an event matcher in a bean connector.

Parameters:

matchPropertyNames - if true, match property change events against the specified property names, if false filter them

propertyNames - the property names to consider

See Also:

GlazedLists.beanConnector(Class, Matcher)

count

public static <E> int count(Collection<E> collection,
                            Matcher<? super E> matcher)

Iterate through the specified collection and count all elements that match the specified matcher.

Returns:

the number of elements in the collection that are matched

filter

public static <E> boolean filter(Collection<E> collection,
                                 Matcher<? super E> matcher)

Iterate through the specified collection and remove all elements that don't match the specified matcher.

Returns:

true if any elements were removed from the specified Collection

select

public static <E> E[] select(E[] items,
                             Matcher<? super E> matcher)

Return a new array containing only the items that satisfy the matcher.

Parameters:

items - the array of Objects to search

matcher - the criteria for considering an element a match

Returns:

a new array containing only the items that satisfy the matcher

select

public static <E> Collection<? super E> select(Collection<E> collection,
                                               Matcher<? super E> matcher)

Add all elements from the given collection that satisfy the matcher to a new ArrayList.

Parameters:

collection - the Collection to search

matcher - the criteria for considering an element a match

Returns:

a new ArrayList containing the elements which satisfy the matcher

select

public static <E> Collection<? super E> select(Collection<E> collection,
                                               Matcher<? super E> matcher,
                                               Collection<? super E> results)

Add all elements from the given collection that satisfy the matcher to the given results Collection. results can be any Collection that supports the Collection.add(E) operation.

Parameters:

collection - the Collection to search

matcher - the criteria for considering an element a match

results - the Collection into which matching elements are added

Returns:

the results Collection containing the elements which satisfy the matcher

contains

public static <E> boolean contains(Collection<E> collection,
                                   Matcher<? super E> matcher)

Returns true if the given collection contains an element that satisfies the given matcher; false otherise.

Parameters:

collection - the Collection to search

matcher - the criteria for considering an element a match

Returns:

true if the given collection contains an element that satisfies the given matcher; false otherise

indexOf

public static <E> int indexOf(List<E> list,
                              Matcher<? super E> matcher)

Returns the index of the first element from the given list that satisfies the matcher or -1 if no such element exists.

Parameters:

list - the List to search

matcher - the criteria for considering an element a match

Returns:

the index of the first element from the given list that satisfies the matcher or -1 if no such element exists

or

public static <E> Matcher<E> or(Matcher<? super E>... matchers)

Returns a Matcher which returns a match when any of the given matchers reports a match.

Parameters:

matchers - the Collection of Matchers to combine with an "or" operator

Returns:

a Matcher that combines the matchers via an "or" operator

and

public static <E> Matcher<E> and(Matcher<? super E>... matchers)

Returns a Matcher which returns a match when all of the given matchers report a match.

Parameters:

matchers - the Collection of Matchers to combine with an "and" operator

Returns:

a Matcher that combines the matchers via an "and" operator

types

public static <E> Matcher<E> types(Class... classes)

Returns a Matcher which reports a match when the given object to match is not null and reports on of the given classes as its type.

Parameters:

classes - the object types that are matched

Returns:

a Matcher which reports a match when the given object to match is not null and reports on of the given classes as its type