public final class Filter extends Object
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 | Class and Description |
---|---|
static class |
Filter.FilterType
This enumeration defines the set of possible filter types that may be used for search filters.
|
Modifier and Type | Method and Description |
---|---|
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. |
boolean |
equals(Object obj)
This method does not perform any normalization, other than lowercasing attribute descriptions, and will only
return
true when two filters are identical. |
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.
|
ByteString |
getAssertionValue()
Returns the assertion value for this comparison filter.
|
String |
getAttributeDescription()
Returns the attribute description for this comparison filter, which may be
null if the filter is an
extensible match filter and the extensible matching rule is specified. |
String |
getExtensibleMatchingRule()
Returns the name of the extensible matching rule which should be used for comparing values, which may be
null if the attribute description is provided (in which case equality
matching will be performed). |
Filter.FilterType |
getFilterType()
Returns the type of this filter.
|
Filter |
getNotSubFilter()
Returns the sub-filter for this NOT filter.
|
List<Filter> |
getSubFilters()
Returns an unmodifiable list containing the sub-filters for this AND or OR filter.
|
List<ByteString> |
getSubstringsAny()
Returns an unmodifiable list containing any intermediate substring assertion values for this substrings filter,
which may be an empty if the substrings filter did not include an intermediate substrings.
|
ByteString |
getSubstringsFinal()
Returns the final substring assertion value for this substrings filter, or
null if the substrings filter
did not include an final substring. |
ByteString |
getSubstringsInitial()
Returns the initial substring assertion value for this substrings filter, or
null if the substrings
filter did not include an initial substring. |
ByteString |
getUnrecognizedFilterBytes()
Returns the ASN.1 content associated with this unrecognized filter.
|
byte |
getUnrecognizedFilterTag()
Returns the ASN.1 tag associated with this unrecognized filter.
|
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. |
int |
hashCode()
This method produces a hash-code of the literal filter representation without performing any normalization other
than lowercasing attribute descriptions.
|
boolean |
isDnAttributes()
Returns whether extensible matching should be performed against attributes in an entry's DN.
|
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
.org.forgerock.i18n.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
.org.forgerock.i18n.LocalizedIllegalArgumentException
- If the formatted template is not a valid LDAP string
representation of a filter.escapeAssertionValue(Object)
public Filter.FilterType getFilterType()
public List<Filter> getSubFilters()
UnsupportedOperationException
- If this filter is not an AND or OR filter.public Filter getNotSubFilter()
UnsupportedOperationException
- If this filter is not a NOT filter.public String getAttributeDescription()
null
if the filter is an
extensible match filter and the extensible matching rule
is specified.null
if the filter is an
extensible match filter.UnsupportedOperationException
- If this filter is not an equality, greater than, less than, approximate, presence, substrings, or
extensible match filter.public ByteString getAssertionValue()
UnsupportedOperationException
- If this filter is not an equality, greater than, less than, approximate, or extensible match filter.public ByteString getSubstringsInitial()
null
if the substrings
filter did not include an initial substring.null
if the substrings
filter did not include an initial substring.UnsupportedOperationException
- If this filter is not a substrings filter.public List<ByteString> getSubstringsAny()
UnsupportedOperationException
- If this filter is not a substrings filter.public ByteString getSubstringsFinal()
null
if the substrings filter
did not include an final substring.null
if the substrings filter
did not include an final substring.UnsupportedOperationException
- If this filter is not a substrings filter.public String getExtensibleMatchingRule()
null
if the attribute description
is provided (in which case equality
matching will be performed).null
.UnsupportedOperationException
- If this filter is not an extensible match filter.public boolean isDnAttributes()
UnsupportedOperationException
- If this filter is not an extensible match filter.public byte getUnrecognizedFilterTag()
UnsupportedOperationException
- If this filter is not an unrecognized filter.public ByteString getUnrecognizedFilterBytes()
UnsupportedOperationException
- If this filter is not an unrecognized filter.public boolean equals(Object obj)
true
when two filters are identical. In particular, the attribute descriptions "cn" and
"commonName" will be treated as different, as will AND/OR filters containing the same sub-filters in a different
order. In order to compare filters for equivalence use Matcher.equals(Object)
.public int hashCode()
Matcher.hashCode()
.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-2017 ForgeRock AS.