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 |
approximate(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 approximate(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.valueOfObject(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.valueOfObject(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.valueOfObject(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.valueOfObject(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.valueOfObject(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.valueOfObject(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.valueOfObject(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.valueOfObject(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.valueOfObject(Object)
method.
attributeDescription
- The attribute description.initialSubstring
- The initial sub-string, may be null
if either
finalSubstring
or anySubstrings
are specified.anySubstrings
- The intermediate sub-strings, may be null
or empty if either
finalSubstring
or initialSubstring
are specified.finalSubstring
- The final sub-string, 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.valueOfObject(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 2010-2018 ForgeRock AS.