ca.odell.glazedlists.matchers

Class Matchers


public final class Matchers
extends java.lang.Object

A factory for creating Matchers.
Author:
Jesse Wilson

Method Summary

static
Collection select(Collection collection, E> matcher)
Add all elements from the given collection that satisfy the matcher to a new ArrayList.
static
Collection select(Collection collection, E> matcher, E> results)
Add all elements from the given collection that satisfy the matcher to the given results Collection.
static
E[] select(E[] items, E> matcher)
Return a new array containing only the items that satisfy the matcher.
static
Matcher and(E>... matchers)
Returns a Matcher which returns a match when all of the given matchers report a match.
static
Matcher beanPropertyMatcher(Class 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
Matcher falseMatcher()
Get a Matcher that always returns false, therefore matching nothing..
static
Matcher invert(Matcher original)
Get a Matcher that returns the opposite of the specified Matcher.
static
Matcher isNotNull()
Get a Matcher that returns returns true iff it is given a null object.
static
Matcher isNull()
Get a Matcher that returns returns true iff it is given a non-null object.
static
Matcher or(E>... matchers)
Returns a Matcher which returns a match when any of the given matchers reports a match.
static
Matcher trueMatcher()
Get a Matcher that always returns true, therefore matching everything.
static
Matcher 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
MatcherEditor weakReferenceProxy(MatcherEditor 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.
static
boolean contains(Collection collection, E> matcher)
Returns true if the given collection contains an element that satisfies the given matcher; false otherise.
static
boolean filter(Collection collection, E> matcher)
Iterate through the specified collection and remove all elements that don't match the specified matcher.
static
extends Comparable, E> Matcher rangeMatcher(D start, D end)
Creates a Matcher that matches Comparable objects for containment within the range between the given start and end.
static
extends Comparable, E> Matcher rangeMatcher(D start, D end, Filterator 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
int count(Collection collection, E> matcher)
Iterate through the specified collection and count all elements that match the specified matcher.
static
int indexOf(List list, 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 Matcher
nonNullAndNonEmptyString()
Get a Matcher that returns true iff it is given a non-null and non-empty String.
static Matcher
propertyEventNameMatcher(boolean matchPropertyNames, String... propertyNames)
Create a Matcher that uses the given propertyNames to match PropertyChangeEvents by their property name.

Method Details

Collection select

public static  Collection select(Collection collection,
                                               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

Collection select

public static  Collection select(Collection collection,
                                               E> matcher,
                                               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 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

E[] select

public static  E[] select(E[] items,
                             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

Matcher and

public static  Matcher and(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

Matcher beanPropertyMatcher

public static  Matcher beanPropertyMatcher(Class 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.

Matcher falseMatcher

public static  Matcher falseMatcher()
Get a Matcher that always returns false, therefore matching nothing..

Matcher invert

public static  Matcher invert(Matcher original)
Get a Matcher that returns the opposite of the specified Matcher.

Matcher isNotNull

public static  Matcher isNotNull()
Get a Matcher that returns returns true iff it is given a null object.

Matcher isNull

public static  Matcher isNull()
Get a Matcher that returns returns true iff it is given a non-null object.

Matcher or

public static  Matcher or(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

Matcher trueMatcher

public static  Matcher trueMatcher()
Get a Matcher that always returns true, therefore matching everything.

Matcher types

public static  Matcher 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

MatcherEditor weakReferenceProxy

public static  MatcherEditor weakReferenceProxy(MatcherEditor 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(Listener) in a java.lang.ref.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:
java.lang.ref.WeakReference

boolean contains

public static  boolean contains(Collection collection,
                                   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

boolean filter

public static  boolean filter(Collection collection,
                                 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

extends Comparable, E> Matcher rangeMatcher

public static  Matcher rangeMatcher(D start,
                                                                D end)
Creates a Matcher that matches Comparable objects for containment within the range between the given start and end.

extends Comparable, E> Matcher rangeMatcher

public static  Matcher rangeMatcher(D start,
                                                                D end,
                                                                Filterator 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

int count

public static  int count(Collection collection,
                            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

int indexOf

public static  int indexOf(List list,
                              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

nonNullAndNonEmptyString

public static Matcher nonNullAndNonEmptyString()
Get a Matcher that returns true iff it is given a non-null and non-empty String.

propertyEventNameMatcher

public static Matcher 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)

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