Package org.forgerock.opendj.ldap

Class Filter

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

    • Method Detail

      • 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:
        RFC 4526

      • 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:
        RFC 4526

      • 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:
        format(String, Object...)

      • 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)(!(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.

        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)(!(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.

        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​(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(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 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:
        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 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 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 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.