Class Filter
- java.lang.Object
-
- org.forgerock.opendj.ldap.Filter
-
public final class Filter extends Object
A search filter as defined in RFC 4511. In addition this class also provides support for the absolute true and absolute false filters as defined in RFC 4526.The RFC 4515 string representation of a filter can be generated using the
toString()
methods and parsed using thevalueOf(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);
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Filter.FilterType
This enumeration defines the set of possible filter types that may be used for search filters.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static Filter
alwaysFalse()
Returns theabsolute false
filter as defined in RFC 4526 which is comprised of anor
filter containing zero components.static Filter
alwaysTrue()
Returns theabsolute true
filter as defined in RFC 4526 which is comprised of anand
filter containing zero components.static Filter
and(Collection<Filter> subFilters)
Creates a newand
filter using the provided list of sub-filters.static Filter
and(Filter... subFilters)
Creates a newand
filter using the provided list of sub-filters.static Filter
approximate(String attributeDescription, Object assertionValue)
Creates a newapproximate match
filter using the provided attribute description and assertion value.static Filter
equality(String attributeDescription, Object assertionValue)
Creates a newequality 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 returntrue
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 newextensible 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 benull
if the filter is an extensible match filter and theextensible matching rule
is specified.String
getExtensibleMatchingRule()
Returns the name of the extensible matching rule which should be used for comparing values, which may benull
if theattribute 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, ornull
if the substrings filter did not include an final substring.ByteString
getSubstringsInitial()
Returns the initial substring assertion value for this substrings filter, ornull
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 newgreater or equal
filter using the provided attribute description and assertion value.static Filter
greaterThan(String attributeDescription, Object assertionValue)
Creates a newgreater 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 newless or equal
filter using the provided attribute description and assertion value.static Filter
lessThan(String attributeDescription, Object assertionValue)
Creates a newless than
filter using the provided attribute description and assertion value.Matcher
matcher()
Returns aMatcher
which can be used to compare thisFilter
against entries using the default schema.Matcher
matcher(Schema schema)
Returns aMatcher
which can be used to compare thisFilter
against entries using the providedSchema
.ConditionResult
matches(Entry entry)
Indicates whether thisFilter
matches the providedEntry
using the default schema.static Filter
not(Filter subFilter)
Creates a newnot
filter using the provided sub-filter.static Filter
objectClassPresent()
Returns theobjectClass
presence filter(objectClass=*)
.static Filter
or(Collection<Filter> subFilters)
Creates a newor
filter using the provided list of sub-filters.static Filter
or(Filter... subFilters)
Creates a newor
filter using the provided list of sub-filters.static Filter
present(String attributeDescription)
Creates a newpresent
filter using the provided attribute description.static Filter
substrings(String attributeDescription, Object initialSubstring, Collection<?> anySubstrings, Object finalSubstring)
Creates a newsubstrings
filter using the provided attribute description,initial
,final
, andany
sub-strings.String
toString()
Returns aString
whose contents is the LDAP string representation of thisFilter
.static Filter
unrecognized(byte filterTag, ByteString filterBytes)
Creates a newunrecognized
filter using the provided ASN1 filter tag and content.static Filter
valueOf(String string)
Parses the provided LDAP string representation of a filter as aFilter
.
-
-
-
Method Detail
-
alwaysFalse
public static Filter alwaysFalse()
Returns theabsolute false
filter as defined in RFC 4526 which is comprised of anor
filter containing zero components.- Returns:
- The absolute false filter.
- See Also:
- RFC 4526
-
alwaysTrue
public static Filter alwaysTrue()
Returns theabsolute true
filter as defined in RFC 4526 which is comprised of anand
filter containing zero components.- Returns:
- The absolute true filter.
- See Also:
- RFC 4526
-
and
public static Filter and(Collection<Filter> subFilters)
Creates a newand
filter using the provided list of sub-filters.Creating a new
and
filter with anull
or empty list of sub-filters is equivalent to callingalwaysTrue()
.- Parameters:
subFilters
- The list of sub-filters, may be empty ornull
.- Returns:
- The newly created
and
filter.
-
and
public static Filter and(Filter... subFilters)
Creates a newand
filter using the provided list of sub-filters.Creating a new
and
filter with anull
or empty list of sub-filters is equivalent to callingalwaysTrue()
.- Parameters:
subFilters
- The list of sub-filters, may be empty ornull
.- Returns:
- The newly created
and
filter.
-
approximate
public static Filter approximate(String attributeDescription, Object assertionValue)
Creates a newapproximate match
filter using the provided attribute description and assertion value.If
assertionValue
is not an instance ofByteString
then it will be converted using theByteString.valueOfObject(Object)
method.- Parameters:
attributeDescription
- The attribute description.assertionValue
- The assertion value.- Returns:
- The newly created
approximate match
filter.
-
equality
public static Filter equality(String attributeDescription, Object assertionValue)
Creates a newequality match
filter using the provided attribute description and assertion value.If
assertionValue
is not an instance ofByteString
then it will be converted using theByteString.valueOfObject(Object)
method.- Parameters:
attributeDescription
- The attribute description.assertionValue
- The assertion value.- Returns:
- The newly created
equality match
filter.
-
escapeAssertionValue
public 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. This method may be useful in cases where a filter is to be constructed from a filter template usingString#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);
IfassertionValue
is not an instance ofByteString
then it will be converted using theByteString.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.- Parameters:
assertionValue
- The assertion value.- Returns:
- The LDAP string representation of the provided filter assertion value in a form suitable for substitution directly into a filter string.
- See Also:
format(String, Object...)
-
extensible
public static Filter extensible(String matchingRule, String attributeDescription, Object assertionValue, boolean dnAttributes)
Creates a newextensible match
filter.If
assertionValue
is not an instance ofByteString
then it will be converted using theByteString.valueOfObject(Object)
method.- Parameters:
matchingRule
- The matching rule name, may benull
ifattributeDescription
is specified.attributeDescription
- The attribute description, may benull
ifmatchingRule
is specified.assertionValue
- The assertion value.dnAttributes
- Indicates whether DN matching should be performed.- Returns:
- The newly created
extensible match
filter.
-
greaterOrEqual
public static Filter greaterOrEqual(String attributeDescription, Object assertionValue)
Creates a newgreater or equal
filter using the provided attribute description and assertion value.If
assertionValue
is not an instance ofByteString
then it will be converted using theByteString.valueOfObject(Object)
method.- Parameters:
attributeDescription
- The attribute description.assertionValue
- The assertion value.- Returns:
- The newly created
greater or equal
filter.
-
greaterThan
public static Filter greaterThan(String attributeDescription, Object assertionValue)
Creates a newgreater than
filter using the provided attribute description and assertion value.If
assertionValue
is not an instance ofByteString
then it will be converted using theByteString.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 outernot
filter will often prevent directory servers from optimizing the search using indexes.- Parameters:
attributeDescription
- The attribute description.assertionValue
- The assertion value.- Returns:
- The newly created
greater than
filter.
-
lessOrEqual
public static Filter lessOrEqual(String attributeDescription, Object assertionValue)
Creates a newless or equal
filter using the provided attribute description and assertion value.If
assertionValue
is not an instance ofByteString
then it will be converted using theByteString.valueOfObject(Object)
method.- Parameters:
attributeDescription
- The attribute description.assertionValue
- The assertion value.- Returns:
- The newly created
less or equal
filter.
-
lessThan
public static Filter lessThan(String attributeDescription, Object assertionValue)
Creates a newless than
filter using the provided attribute description and assertion value.If
assertionValue
is not an instance ofByteString
then it will be converted using theByteString.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 outernot
filter will often prevent directory servers from optimizing the search using indexes.- Parameters:
attributeDescription
- The attribute description.assertionValue
- The assertion value.- Returns:
- The newly created
less than
filter.
-
not
public static Filter not(Filter subFilter)
Creates a newnot
filter using the provided sub-filter.- Parameters:
subFilter
- The sub-filter.- Returns:
- The newly created
not
filter.
-
objectClassPresent
public static Filter objectClassPresent()
Returns theobjectClass
presence filter(objectClass=*)
.A call to this method is equivalent to but more efficient than the following code:
Filter.present("objectClass");
- Returns:
- The
objectClass
presence filter(objectClass=*)
.
-
or
public static Filter or(Collection<Filter> subFilters)
Creates a newor
filter using the provided list of sub-filters.Creating a new
or
filter with anull
or empty list of sub-filters is equivalent to callingalwaysFalse()
.- Parameters:
subFilters
- The list of sub-filters, may be empty ornull
.- Returns:
- The newly created
or
filter.
-
or
public static Filter or(Filter... subFilters)
Creates a newor
filter using the provided list of sub-filters.Creating a new
or
filter with anull
or empty list of sub-filters is equivalent to callingalwaysFalse()
.- Parameters:
subFilters
- The list of sub-filters, may be empty ornull
.- Returns:
- The newly created
or
filter.
-
present
public static Filter present(String attributeDescription)
Creates a newpresent
filter using the provided attribute description.- Parameters:
attributeDescription
- The attribute description.- Returns:
- The newly created
present
filter.
-
substrings
public static Filter substrings(String attributeDescription, Object initialSubstring, Collection<?> anySubstrings, Object finalSubstring)
Creates a newsubstrings
filter using the provided attribute description,initial
,final
, andany
sub-strings.Any substrings which are not instances of
ByteString
will be converted using theByteString.valueOfObject(Object)
method.- Parameters:
attributeDescription
- The attribute description.initialSubstring
- The initial sub-string, may benull
if eitherfinalSubstring
oranySubstrings
are specified.anySubstrings
- The intermediate sub-strings, may benull
or empty if eitherfinalSubstring
orinitialSubstring
are specified.finalSubstring
- The final sub-string, may benull
if eitherinitialSubstring
oranySubstrings
are specified.- Returns:
- The newly created
substrings
filter.
-
unrecognized
public static Filter unrecognized(byte filterTag, ByteString filterBytes)
Creates a newunrecognized
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.- Parameters:
filterTag
- The ASN.1 tag.filterBytes
- The filter content.- Returns:
- The newly created
unrecognized
filter.
-
valueOf
public static Filter valueOf(String string)
Parses the provided LDAP string representation of a filter as aFilter
.- Parameters:
string
- The LDAP string representation of a filter.- Returns:
- The parsed
Filter
. - Throws:
org.forgerock.i18n.LocalizedIllegalArgumentException
- Ifstring
is not a valid LDAP string representation of a filter.- See Also:
format(String, Object...)
-
format
public static Filter format(String template, Object... assertionValues)
Creates a new filter using the provided filter template and unescaped assertion values. This method first escapes each of the assertion values and then substitutes them into the template usingString.format(String, Object...)
. Finally, the formatted string is parsed as an LDAP filter usingvalueOf(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 ofByteString
will be converted using theByteString.valueOfObject(Object)
method.- Parameters:
template
- The filter template.assertionValues
- The assertion values to be substituted into the template.- Returns:
- The formatted template parsed as a
Filter
. - Throws:
org.forgerock.i18n.LocalizedIllegalArgumentException
- If the formatted template is not a valid LDAP string representation of a filter.- See Also:
escapeAssertionValue(Object)
-
getFilterType
public Filter.FilterType getFilterType()
Returns the type of this filter.- Returns:
- The type of this filter.
-
getSubFilters
public List<Filter> getSubFilters()
Returns an unmodifiable list containing the sub-filters for this AND or OR filter.- Returns:
- An unmodifiable list containing the sub-filters for this AND or OR filter.
- Throws:
UnsupportedOperationException
- If this filter is not an AND or OR filter.
-
getNotSubFilter
public Filter getNotSubFilter()
Returns the sub-filter for this NOT filter.- Returns:
- The sub-filter for this NOT filter.
- Throws:
UnsupportedOperationException
- If this filter is not a NOT filter.
-
getAttributeDescription
public String getAttributeDescription()
Returns the attribute description for this comparison filter, which may benull
if the filter is an extensible match filter and theextensible matching rule
is specified.- Returns:
- The attribute description for this comparison filter, which may be
null
if the filter is an extensible match filter. - Throws:
UnsupportedOperationException
- If this filter is not an equality, greater than, less than, approximate, presence, substrings, or extensible match filter.
-
getAssertionValue
public ByteString getAssertionValue()
Returns the assertion value for this comparison filter.- Returns:
- The assertion value for this comparison filter.
- Throws:
UnsupportedOperationException
- If this filter is not an equality, greater than, less than, approximate, or extensible match filter.
-
getSubstringsInitial
public ByteString getSubstringsInitial()
Returns the initial substring assertion value for this substrings filter, ornull
if the substrings filter did not include an initial substring.- Returns:
- The initial substring assertion value for this substrings filter, or
null
if the substrings filter did not include an initial substring. - Throws:
UnsupportedOperationException
- If this filter is not a substrings filter.
-
getSubstringsAny
public 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.- Returns:
- An unmodifiable list containing any intermediate substring assertion values for this substrings filter
- Throws:
UnsupportedOperationException
- If this filter is not a substrings filter.
-
getSubstringsFinal
public ByteString getSubstringsFinal()
Returns the final substring assertion value for this substrings filter, ornull
if the substrings filter did not include an final substring.- Returns:
- The final substring assertion value for this substrings filter, or
null
if the substrings filter did not include an final substring. - Throws:
UnsupportedOperationException
- If this filter is not a substrings filter.
-
getExtensibleMatchingRule
public String getExtensibleMatchingRule()
Returns the name of the extensible matching rule which should be used for comparing values, which may benull
if theattribute description
is provided (in which case equality matching will be performed).- Returns:
- The name of the extensible matching rule which should be used for comparing values, which may be
null
. - Throws:
UnsupportedOperationException
- If this filter is not an extensible match filter.
-
isDnAttributes
public boolean isDnAttributes()
Returns whether extensible matching should be performed against attributes in an entry's DN.- Returns:
- Whether extensible matching should be performed against attributes in an entry's DN.
- Throws:
UnsupportedOperationException
- If this filter is not an extensible match filter.
-
getUnrecognizedFilterTag
public byte getUnrecognizedFilterTag()
Returns the ASN.1 tag associated with this unrecognized filter.- Returns:
- The ASN.1 tag associated with this unrecognized filter.
- Throws:
UnsupportedOperationException
- If this filter is not an unrecognized filter.
-
getUnrecognizedFilterBytes
public ByteString getUnrecognizedFilterBytes()
Returns the ASN.1 content associated with this unrecognized filter.- Returns:
- The ASN.1 content associated with this unrecognized filter.
- Throws:
UnsupportedOperationException
- If this filter is not an unrecognized filter.
-
equals
public boolean equals(Object obj)
This method does not perform any normalization, other than lowercasing attribute descriptions, and will only returntrue
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 useMatcher.equals(Object)
.
-
hashCode
public int hashCode()
This method produces a hash-code of the literal filter representation without performing any normalization other than lowercasing attribute descriptions. 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 useMatcher.hashCode()
.
-
matcher
public Matcher matcher()
Returns aMatcher
which can be used to compare thisFilter
against entries using the default schema.- Returns:
- The
Matcher
.
-
matcher
public Matcher matcher(Schema schema)
Returns aMatcher
which can be used to compare thisFilter
against entries using the providedSchema
.- Parameters:
schema
- The schema which theMatcher
should use for comparisons.- Returns:
- The
Matcher
.
-
matches
public ConditionResult matches(Entry entry)
Indicates whether thisFilter
matches the providedEntry
using the default schema.Calling this method is equivalent to the following:
matcher().matches(entry);
- Parameters:
entry
- The entry to be matched.- Returns:
- The result of matching the provided
Entry
against thisFilter
using the default schema.
-
-