public final class Filter extends Object
This class provides many factory methods for creating common types of filter.
Applications interact with a filter using FilterVisitor which is
applied to a filter using the accept(FilterVisitor, Object) method.
The RFC 4515 string representation of a filter can be generated using the
toString() methods and parsed using the valueOf(String)
factory method.
Filters can be constructed using the various factory methods. For example,
the following code illustrates how to create a filter having the string
representation "(&(cn=bjensen)(age>=21))":
import static org.forgerock.opendj.Filter.*;
Filter filter = and(equality("cn", "bjensen"), greaterOrEqual("age", 21));
// Alternatively use a filter template:
Filter filter = Filter.format("(&(cn=%s)(age>=%s))", "bjensen", 21);
| Modifier and Type | Method and Description |
|---|---|
<R,P> R |
accept(FilterVisitor<R,P> v,
P p)
Applies a
FilterVisitor to this Filter. |
static Filter |
alwaysFalse()
Returns the
absolute false filter as defined in RFC 4526 which is
comprised of an or filter containing zero components. |
static Filter |
alwaysTrue()
Returns the
absolute true filter as defined in RFC 4526 which is
comprised of an and filter containing zero components. |
static Filter |
and(Collection<Filter> subFilters)
Creates a new
and filter using the provided list of sub-filters. |
static Filter |
and(Filter... subFilters)
Creates a new
and filter using the provided list of sub-filters. |
static Filter |
approx(String attributeDescription,
Object assertionValue)
Creates a new
approximate match filter using the provided
attribute description and assertion value. |
static Filter |
equality(String attributeDescription,
Object assertionValue)
Creates a new
equality match filter using the provided attribute
description and assertion value. |
static String |
escapeAssertionValue(Object assertionValue)
Returns the LDAP string representation of the provided filter assertion
value in a form suitable for substitution directly into a filter string.
|
static Filter |
extensible(String matchingRule,
String attributeDescription,
Object assertionValue,
boolean dnAttributes)
Creates a new
extensible match filter. |
static Filter |
format(String template,
Object... assertionValues)
Creates a new filter using the provided filter template and unescaped
assertion values.
|
static Filter |
greaterOrEqual(String attributeDescription,
Object assertionValue)
Creates a new
greater or equal filter using the provided
attribute description and assertion value. |
static Filter |
greaterThan(String attributeDescription,
Object assertionValue)
Creates a new
greater than filter using the provided attribute
description and assertion value. |
static Filter |
lessOrEqual(String attributeDescription,
Object assertionValue)
Creates a new
less or equal filter using the provided attribute
description and assertion value. |
static Filter |
lessThan(String attributeDescription,
Object assertionValue)
Creates a new
less than filter using the provided attribute
description and assertion value. |
Matcher |
matcher()
Returns a
Matcher which can be used to compare this
Filter against entries using the default schema. |
Matcher |
matcher(Schema schema)
Returns a
Matcher which can be used to compare this
Filter against entries using the provided Schema. |
ConditionResult |
matches(Entry entry)
Indicates whether this
Filter matches the provided Entry
using the default schema. |
static Filter |
not(Filter subFilter)
Creates a new
not filter using the provided sub-filter. |
static Filter |
objectClassPresent()
Returns the
objectClass presence filter (objectClass=*). |
static Filter |
or(Collection<Filter> subFilters)
Creates a new
or filter using the provided list of sub-filters. |
static Filter |
or(Filter... subFilters)
Creates a new
or filter using the provided list of sub-filters. |
static Filter |
present(String attributeDescription)
Creates a new
present filter using the provided attribute
description. |
static Filter |
substrings(String attributeDescription,
Object initialSubstring,
Collection<?> anySubstrings,
Object finalSubstring)
Creates a new
substrings filter using the provided attribute
description, initial, final, and any sub-strings. |
String |
toString()
Returns a
String whose contents is the LDAP string representation
of this Filter. |
static Filter |
unrecognized(byte filterTag,
ByteString filterBytes)
Creates a new
unrecognized filter using the provided ASN1 filter
tag and content. |
static Filter |
valueOf(String string)
Parses the provided LDAP string representation of a filter as a
Filter. |
public static Filter alwaysFalse()
absolute false filter as defined in RFC 4526 which is
comprised of an or filter containing zero components.public static Filter alwaysTrue()
absolute true filter as defined in RFC 4526 which is
comprised of an and filter containing zero components.public static Filter and(Collection<Filter> subFilters)
and filter using the provided list of sub-filters.
Creating a new and filter with a null or empty list of
sub-filters is equivalent to calling alwaysTrue().
subFilters - The list of sub-filters, may be empty or null.and filter.public static Filter and(Filter... subFilters)
and filter using the provided list of sub-filters.
Creating a new and filter with a null or empty list of
sub-filters is equivalent to calling alwaysTrue().
subFilters - The list of sub-filters, may be empty or null.and filter.public static Filter approx(String attributeDescription, Object assertionValue)
approximate match filter using the provided
attribute description and assertion value.
If assertionValue is not an instance of ByteString then
it will be converted using the ByteString.valueOf(Object) method.
attributeDescription - The attribute description.assertionValue - The assertion value.approximate match filter.public static Filter equality(String attributeDescription, Object assertionValue)
equality match filter using the provided attribute
description and assertion value.
If assertionValue is not an instance of ByteString then
it will be converted using the ByteString.valueOf(Object) method.
attributeDescription - The attribute description.assertionValue - The assertion value.equality match filter.public static String escapeAssertionValue(Object assertionValue)
String#format(String, Object...).
The following example illustrates two approaches to constructing an
equality filter:
// This may contain user input.
String assertionValue = ...;
// Using the equality filter constructor:
Filter filter = Filter.equality("cn", assertionValue);
// Using a String template:
String filterTemplate = "(cn=%s)";
String filterString = String.format(filterTemplate,
Filter.escapeAssertionValue(assertionValue));
Filter filter = Filter.valueOf(filterString);
If assertionValue is not an instance of ByteString then
it will be converted using the ByteString.valueOf(Object) method.
Note: assertion values do not and should not be escaped before
passing them to constructors like equality(String, Object).
Escaping is only required when creating filter strings.
assertionValue - The assertion value.format(String, Object...)public static Filter extensible(String matchingRule, String attributeDescription, Object assertionValue, boolean dnAttributes)
extensible match filter.
If assertionValue is not an instance of ByteString then
it will be converted using the ByteString.valueOf(Object) method.
matchingRule - The matching rule name, may be null if
attributeDescription is specified.attributeDescription - The attribute description, may be null if
matchingRule is specified.assertionValue - The assertion value.dnAttributes - Indicates whether DN matching should be performed.extensible match filter.public static Filter greaterOrEqual(String attributeDescription, Object assertionValue)
greater or equal filter using the provided
attribute description and assertion value.
If assertionValue is not an instance of ByteString then
it will be converted using the ByteString.valueOf(Object) method.
attributeDescription - The attribute description.assertionValue - The assertion value.greater or equal filter.public static Filter greaterThan(String attributeDescription, Object assertionValue)
greater than filter using the provided attribute
description and assertion value.
If assertionValue is not an instance of ByteString then
it will be converted using the ByteString.valueOf(Object) method.
NOTE: since LDAP does not support greater than
comparisons, this method returns a filter of the form
(&(type>=value)(!(type=value))). An alternative is to return a
filter of the form (!(type<=value)) , however the outer
not filter will often prevent directory servers from optimizing
the search using indexes.
attributeDescription - The attribute description.assertionValue - The assertion value.greater than filter.public static Filter lessOrEqual(String attributeDescription, Object assertionValue)
less or equal filter using the provided attribute
description and assertion value.
If assertionValue is not an instance of ByteString then
it will be converted using the ByteString.valueOf(Object) method.
attributeDescription - The attribute description.assertionValue - The assertion value.less or equal filter.public static Filter lessThan(String attributeDescription, Object assertionValue)
less than filter using the provided attribute
description and assertion value.
If assertionValue is not an instance of ByteString then
it will be converted using the ByteString.valueOf(Object) method.
NOTE: since LDAP does not support less than comparisons,
this method returns a filter of the form
(&(type<=value)(!(type=value))). An alternative is to return a
filter of the form (!(type>=value)) , however the outer
not filter will often prevent directory servers from optimizing
the search using indexes.
attributeDescription - The attribute description.assertionValue - The assertion value.less than filter.public static Filter not(Filter subFilter)
not filter using the provided sub-filter.subFilter - The sub-filter.not filter.public static Filter objectClassPresent()
objectClass presence filter (objectClass=*).
A call to this method is equivalent to but more efficient than the following code:
Filter.present("objectClass");
objectClass presence filter (objectClass=*).public static Filter or(Collection<Filter> subFilters)
or filter using the provided list of sub-filters.
Creating a new or filter with a null or empty list of
sub-filters is equivalent to calling alwaysFalse().
subFilters - The list of sub-filters, may be empty or null.or filter.public static Filter or(Filter... subFilters)
or filter using the provided list of sub-filters.
Creating a new or filter with a null or empty list of
sub-filters is equivalent to calling alwaysFalse().
subFilters - The list of sub-filters, may be empty or null.or filter.public static Filter present(String attributeDescription)
present filter using the provided attribute
description.attributeDescription - The attribute description.present filter.public static Filter substrings(String attributeDescription, Object initialSubstring, Collection<?> anySubstrings, Object finalSubstring)
substrings filter using the provided attribute
description, initial, final, and any sub-strings.
Any substrings which are not instances of ByteString will be
converted using the ByteString.valueOf(Object) method.
attributeDescription - The attribute description.initialSubstring - The initial sub-string, may be null if either
finalSubstring or anySubstrings are specified.anySubstrings - The final sub-string, may be null or empty if either
finalSubstring or initialSubstring are
specified.finalSubstring - The final sub-string, may be null, may be null
if either initialSubstring or anySubstrings
are specified.substrings filter.public static Filter unrecognized(byte filterTag, ByteString filterBytes)
unrecognized filter using the provided ASN1 filter
tag and content. This type of filter should be used for filters which are
not part of the standard filter definition.filterTag - The ASN.1 tag.filterBytes - The filter content.unrecognized filter.public static Filter valueOf(String string)
Filter.string - The LDAP string representation of a filter.Filter.LocalizedIllegalArgumentException - If string is not a valid LDAP string representation
of a filter.format(String, Object...)public static Filter format(String template, Object... assertionValues)
String.format(String, Object...). Finally, the formatted string
is parsed as an LDAP filter using valueOf(String).
This method may be useful in cases where the structure of a filter is not known at compile time, for example, it may be obtained from a configuration file. Example usage:
String template = "(|(cn=%s)(uid=user.%s))"; Filter filter = Filter.format(template, "alice", 123);Any assertion values which are not instances of
ByteString will
be converted using the ByteString.valueOf(Object) method.template - The filter template.assertionValues - The assertion values to be substituted into the template.Filter.LocalizedIllegalArgumentException - If the formatted template is not a valid LDAP string
representation of a filter.escapeAssertionValue(Object)public <R,P> R accept(FilterVisitor<R,P> v, P p)
FilterVisitor to this Filter.R - The return type of the visitor's methods.P - The type of the additional parameters to the visitor's
methods.v - The filter visitor.p - Optional additional visitor parameter.public Matcher matcher()
Matcher which can be used to compare this
Filter against entries using the default schema.Matcher.public Matcher matcher(Schema schema)
Matcher which can be used to compare this
Filter against entries using the provided Schema.schema - The schema which the Matcher should use for
comparisons.Matcher.public ConditionResult matches(Entry entry)
Filter matches the provided Entry
using the default schema.
Calling this method is equivalent to the following:
matcher().matches(entry);
entry - The entry to be matched.Entry against this
Filter using the default schema.Copyright © 2011-2015 ForgeRock AS. All Rights Reserved.