Package org.forgerock.opendj.ldap

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 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);
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Filter.FilterType
    This enumeration defines the set of possible filter types that may be used for search filters.

  • Method Summary

    Modifier and Type
    Method
    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 an optimized new and filter using the provided list of sub-filters.
    static Filter
    and(Collection<Filter> subFilters, boolean optimize)
    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 a 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 an optimized new not filter using the provided sub-filter.
    static Filter
    not(Filter subFilter, boolean optimize)
    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 an optimized new or filter using the provided list of sub-filters.
    static Filter
    or(Collection<Filter> subFilters, boolean optimize)
    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(boolean bool)
    Returns an alwaysTrue() or alwaysFalse() Filter depending on the provided value.
    static Filter
    valueOf(String string)
    Parses the provided LDAP string representation of a filter as a Filter.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • alwaysFalse

      public static Filter alwaysFalse()
      Returns the absolute false filter as defined in RFC 4526 which is comprised of an or filter containing zero components.
      Returns:
      The absolute false filter.
      See Also:

    • alwaysTrue

      public static Filter alwaysTrue()
      Returns the absolute true filter as defined in RFC 4526 which is comprised of an and filter containing zero components.
      Returns:
      The absolute true filter.
      See Also:

    • and

      public static Filter and(Collection<Filter> subFilters, boolean optimize)
      Creates a new 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().

      Parameters:
      subFilters - The list of sub-filters, may be empty or null.
      optimize - Whether to optimize the filter.
      Returns:
      The newly created and filter.

    • and

      public static Filter and(Collection<Filter> subFilters)
      Creates an optimized new and filter using the provided list of sub-filters. This method is equivalent to calling and(subFilters, true).
      Parameters:
      subFilters - The list of sub-filters, may be empty or null.
      Returns:
      The newly created and filter.

    • and

      public static Filter and(Filter... subFilters)
      Creates a new 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().

      Parameters:
      subFilters - The list of sub-filters, may be empty or null.
      Returns:
      The newly created and filter.

    • approximate

      public static Filter approximate(String attributeDescription, Object assertionValue)
      Creates a new 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.

      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 new 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.

      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 using 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.

      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:

    • extensible

      public static Filter extensible(String matchingRule, String attributeDescription, Object assertionValue, boolean dnAttributes)
      Creates a new extensible match filter.

      If assertionValue is not an instance of ByteString then it will be converted using the ByteString.valueOfObject(Object) method.

      Parameters:
      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.
      Returns:
      The newly created extensible match filter.

    • greaterOrEqual

      public static Filter greaterOrEqual(String attributeDescription, Object assertionValue)
      Creates a new 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.

      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 new 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)).

      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 new 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.

      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 new 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)).

      Parameters:
      attributeDescription - The attribute description.
      assertionValue - The assertion value.
      Returns:
      The newly created less than filter.

    • not

      public static Filter not(Filter subFilter)
      Creates an optimized new not filter using the provided sub-filter. This method is equivalent to calling not(subFilter, true).
      Parameters:
      subFilter - The sub-filter.
      Returns:
      The newly created not filter.

    • not

      public static Filter not(Filter subFilter, boolean optimize)
      Creates a new not filter using the provided sub-filter.
      Parameters:
      subFilter - The sub-filter.
      optimize - Whether to optimize the filter.
      Returns:
      The newly created not filter.

    • objectClassPresent

      public static Filter objectClassPresent()
      Returns the objectClass 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, boolean optimize)
      Creates a new 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().

      Parameters:
      subFilters - The list of sub-filters, may be empty or null.
      optimize - Whether to optimize the filter.
      Returns:
      The newly created or filter.

    • or

      public static Filter or(Collection<Filter> subFilters)
      Creates an optimized new or filter using the provided list of sub-filters. This method is equivalent to calling or(subFilters, true).

      Creating a new or filter with a null or empty list of sub-filters is equivalent to calling alwaysFalse().

      Parameters:
      subFilters - The list of sub-filters, may be empty or null.
      Returns:
      The newly created or filter.

    • or

      public static Filter or(Filter... subFilters)
      Creates a new 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().

      Parameters:
      subFilters - The list of sub-filters, may be empty or null.
      Returns:
      The newly created or filter.

    • present

      public static Filter present(String attributeDescription)
      Creates a new present 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 new 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.

      Parameters:
      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.
      Returns:
      The newly created substrings filter.

    • unrecognized

      public static Filter unrecognized(byte filterTag, ByteString filterBytes)
      Creates a new 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.
      Parameters:
      filterTag - The ASN.1 tag.
      filterBytes - The filter content.
      Returns:
      The newly created unrecognized filter.

    • valueOf

      public static Filter valueOf(boolean bool)
      Returns an alwaysTrue() or alwaysFalse() Filter depending on the provided value.
      Parameters:
      bool - The boolean representation of a filter.
      Returns:
      alwaysTrue() if bool is true. Otherwise, returns alwaysFalse().

    • valueOf

      public static Filter valueOf(String string)
      Parses the provided LDAP string representation of a filter as a Filter.
      Parameters:
      string - The LDAP string representation of a filter.
      Returns:
      The parsed Filter.
      Throws:
      LocalizedIllegalArgumentException - If string is not a valid LDAP string representation of a filter.
      See Also:

    • 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 using 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.
      Parameters:
      template - The filter template.
      assertionValues - The assertion values to be substituted into the template.
      Returns:
      The formatted template parsed as a Filter.
      Throws:
      LocalizedIllegalArgumentException - If the formatted template is not a valid LDAP string representation of a filter.
      See Also:

    • 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 be null if the filter is an extensible match filter and the extensible 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, or null 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, or null if the substrings filter did not include a final substring.
      Returns:
      The final substring assertion value for this substrings filter, or null if the substrings filter did not include a 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 be null if the attribute 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 return 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).
      Overrides:
      equals in class 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 use Matcher.hashCode().
      Overrides:
      hashCode in class Object

    • matcher

      public Matcher matcher()
      Returns a Matcher which can be used to compare this Filter against entries using the default schema.
      Returns:
      The Matcher.

    • matcher

      public Matcher matcher(Schema schema)
      Returns a Matcher which can be used to compare this Filter against entries using the provided Schema.
      Parameters:
      schema - The schema which the Matcher should use for comparisons.
      Returns:
      The Matcher.

    • matches

      public ConditionResult matches(Entry entry)
      Indicates whether this Filter matches the provided Entry 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 this Filter using the default schema.

    • toString

      public String toString()
      Returns a String whose contents is the LDAP string representation of this Filter.
      Overrides:
      toString in class Object
      Returns:
      The LDAP string representation of this Filter.