org.apache.directory.api.ldap.model.filter

Class FilterParser

java.lang.Object

org.apache.directory.api.ldap.model.filter.FilterParser

public final class FilterParser
extends Object

This class parse a Ldap filter. The grammar is given in RFC 4515

Author:

Apache Directory Project

Constructor Summary

Constructors

Modifier	Constructor and Description
private	FilterParser()

Method Summary

Modifier and Type	Method and Description
static ExprNode	parse(SchemaManager schemaManager, String filter) Parses a search filter from it's string representation to an expression node object, using the provided SchemaManager
static ExprNode	parse(SchemaManager schemaManager, String filter, boolean relaxed) Parses a search filter from it's string representation to an expression node object, using the provided SchemaManager
static ExprNode	parse(String filter) Parses a search filter from it's string representation to an expression node object.
static ExprNode	parse(String filter, boolean relaxed) Parses a search filter from it's string representation to an expression node object.
private static Value	parseAssertionValue(SchemaManager schemaManager, byte[] filterBytes, org.apache.directory.api.util.Position pos) An assertion value : assertionvalue = valueencoding valueencoding = 0*(normal / escaped) normal = UTF1SUBSET / UTFMB escaped = '\' HEX HEX HEX = '0'-'9' / 'A'-'F' / 'a'-'f' UTF1SUBSET = %x01-27 / %x2B-5B / %x5D-7F (Everything but '\0', '*', '(', ')' and '\') UTFMB = UTF2 / UTF3 / UTF4 UTF0 = %x80-BF UTF2 = %xC2-DF UTF0 UTF3 = %xE0 %xA0-BF UTF0 / %xE1-EC UTF0 UTF0 / %xED %x80-9F UTF0 / %xEE-EF UTF0 UTF0 UTF4 = %xF0 %x90-BF UTF0 UTF0 / %xF1-F3 UTF0 UTF0 UTF0 / %xF4 %x80-8F UTF0 UTF0 With the specific constraints (RFC 4515): "The <valueencoding> rule ensures that the entire filter string is a" "valid UTF-8 string and provides that the octets that represent the" "ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII" "0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a" "backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits" "representing the value of the encoded octet."
private static Value	parseAssertionValue(SchemaManager schemaManager, String attribute, byte[] filterBytes, org.apache.directory.api.util.Position pos) An assertion value : assertionvalue = valueencoding valueencoding = 0*(normal / escaped) normal = UTF1SUBSET / UTFMB escaped = '\' HEX HEX HEX = '0'-'9' / 'A'-'F' / 'a'-'f' UTF1SUBSET = %x01-27 / %x2B-5B / %x5D-7F (Everything but '\0', '*', '(', ')' and '\') UTFMB = UTF2 / UTF3 / UTF4 UTF0 = %x80-BF UTF2 = %xC2-DF UTF0 UTF3 = %xE0 %xA0-BF UTF0 / %xE1-EC UTF0 UTF0 / %xED %x80-9F UTF0 / %xEE-EF UTF0 UTF0 UTF4 = %xF0 %x90-BF UTF0 UTF0 / %xF1-F3 UTF0 UTF0 UTF0 / %xF4 %x80-8F UTF0 UTF0 With the specific constraints (RFC 4515): "The <valueencoding< rule ensures that the entire filter string is a" "valid UTF-8 string and provides that the octets that represent the" "ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII" "0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a" "backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits" "representing the value of the encoded octet."
private static ExprNode	parseBranchNode(SchemaManager schemaManager, ExprNode node, byte[] filterBytes, org.apache.directory.api.util.Position pos, boolean relaxed) Parse AND, OR and NOT nodes : and = '&' filterlist or = '|' filterlist not = '!'
private static ExprNode	parseExtensible(SchemaManager schemaManager, String attribute, byte[] filterBytes, org.apache.directory.api.util.Position pos, boolean relaxed) Parse an extensible extensible = ( attr [":dn"] [':' oid] ":=" assertionvalue ) / ( [":dn"] ':' oid ":=" assertionvalue ) matchingrule = ":" oid
private static ExprNode	parseFilterComp(SchemaManager schemaManager, byte[] filterBytes, org.apache.directory.api.util.Position pos, boolean relaxed) filtercomp = and / or / not / item and = '&' WSP* filterlist or = '|' WSP* filterlist not = '!'
private static ExprNode	parseFilterInternal(SchemaManager schemaManager, byte[] filterBytes, org.apache.directory.api.util.Position pos, boolean relaxed) Parse the grammar rule : filter ::= WSP* '(' WSP* filterComp WSP* ')' WSP*
private static ExprNode	parseItem(SchemaManager schemaManager, byte[] filterBytes, org.apache.directory.api.util.Position pos, byte b, boolean relaxed) Parse the following grammar : item = simple / present / substring / extensible simple = attr WSP* filtertype WSP* assertionvalue filtertype = '=' / '~=' / '>=' / '<=' present = attr WSP* '=' '*' substring = attr WSP* '=' WSP* [initial] any [final] extensible = ( attr [":dn"] [':' oid] ":=" assertionvalue ) / ( [":dn"] ':' oid ":=" assertionvalue ) matchingrule = ":" oid An item starts with an attribute or a colon.
private static ExprNode	parsePresenceEqOrSubstring(SchemaManager schemaManager, String attribute, byte[] filterBytes, org.apache.directory.api.util.Position pos) Here is the grammar to parse : simple ::= '=' assertionValue present ::= '=' '*' substring ::= '=' [initial] any [final] initial ::= assertionValue any ::= '*' ( assertionValue '*')* As we can see, there is an ambiguity in the grammar : attr=* can be seen as a present or as a substring.
private static ExprNode	parseSubstring(SchemaManager schemaManager, String attribute, Value initial, byte[] filterBytes, org.apache.directory.api.util.Position pos) Parse a substring
private static void	skipWhiteSpaces(byte[] filter, org.apache.directory.api.util.Position pos) Skip the white spaces (0x20, 0x09, 0x0a and 0x0d)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FilterParser

private FilterParser()

Method Detail

parse

public static ExprNode parse(String filter)
                      throws ParseException

Parses a search filter from it's string representation to an expression node object.

Parameters:

filter - the search filter in it's string representation

Returns:

the expression node object

Throws:

ParseException - If the filter is invalid

parse

public static ExprNode parse(String filter,
                             boolean relaxed)
                      throws ParseException

Parses a search filter from it's string representation to an expression node object. In relaxed mode the filter may violate RFC 4515, e.g. the underscore in attribute names is allowed.

Parameters:

filter - the search filter in it's string representation

relaxed - true to parse the filter in relaxed mode

Returns:

the expression node object

Throws:

ParseException - If the filter is invalid

parse

public static ExprNode parse(SchemaManager schemaManager,
                             String filter)
                      throws ParseException

Parses a search filter from it's string representation to an expression node object, using the provided SchemaManager

Parameters:

schemaManager - The SchemaManager to use

filter - the search filter in it's string representation

Returns:

the expression node object

Throws:

ParseException - If the filter is invalid

skipWhiteSpaces

private static void skipWhiteSpaces(byte[] filter,
                                    org.apache.directory.api.util.Position pos)

Skip the white spaces (0x20, 0x09, 0x0a and 0x0d)

Parameters:

filter - The filter being parsed

pos - The current position in the filter

parse

public static ExprNode parse(SchemaManager schemaManager,
                             String filter,
                             boolean relaxed)
                      throws ParseException

Parses a search filter from it's string representation to an expression node object, using the provided SchemaManager

Parameters:

schemaManager - The SchemaManager to use

filter - the search filter in it's string representation

relaxed - true to parse the filter in relaxed mode

Returns:

the expression node object

Throws:

ParseException - If the filter is invalid

parseExtensible

private static ExprNode parseExtensible(SchemaManager schemaManager,
                                        String attribute,
                                        byte[] filterBytes,
                                        org.apache.directory.api.util.Position pos,
                                        boolean relaxed)
                                 throws LdapException,
                                        ParseException

Parse an extensible

 extensible     = ( attr [":dn"] [':' oid] ":=" assertionvalue )
                  / ( [":dn"] ':' oid ":=" assertionvalue )
 matchingrule   = ":" oid
 

Parameters:

schemaManager - The SchemaManager

attribute - The filter's attribute

filterBytes - The filter bytes to parse

pos - The position in the filter bytes

relaxed - If the filter is analyzed in relaxed mode or not

Returns:

the created ExprNode

Throws:

ParseException - If the Node can't be parsed

LdapException - If we met an error while parsing a filter element

parseAssertionValue

private static Value parseAssertionValue(SchemaManager schemaManager,
                                         String attribute,
                                         byte[] filterBytes,
                                         org.apache.directory.api.util.Position pos)
                                  throws ParseException,
                                         LdapInvalidAttributeValueException

An assertion value :

 assertionvalue = valueencoding
 valueencoding  = 0*(normal / escaped)
 normal         = UTF1SUBSET / UTFMB
 escaped        = '\' HEX HEX
 HEX            = '0'-'9' / 'A'-'F' / 'a'-'f'
 UTF1SUBSET     = %x01-27 / %x2B-5B / %x5D-7F (Everything but '\0', '*', '(', ')' and '\')
 UTFMB          = UTF2 / UTF3 / UTF4
 UTF0           = %x80-BF
 UTF2           = %xC2-DF UTF0
 UTF3           = %xE0 %xA0-BF UTF0 / %xE1-EC UTF0 UTF0 / %xED %x80-9F UTF0 / %xEE-EF UTF0 UTF0
 UTF4           = %xF0 %x90-BF UTF0 UTF0 / %xF1-F3 UTF0 UTF0 UTF0 / %xF4 %x80-8F UTF0 UTF0
 

With the specific constraints (RFC 4515):

    "The <valueencoding< rule ensures that the entire filter string is a"
    "valid UTF-8 string and provides that the octets that represent the"
    "ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII"
    "0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a"
    "backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits"
    "representing the value of the encoded octet."
 

The incoming String is already transformed from UTF-8 to unicode, so we must assume that the grammar we have to check is the following :

 assertionvalue = valueencoding
 valueencoding  = 0*(normal / escaped)
 normal         = unicodeSubset
 escaped        = '\' HEX HEX
 HEX            = '0'-'9' / 'A'-'F' / 'a'-'f'
 unicodeSubset     = %x01-27 / %x2B-5B / %x5D-FFFF
 

Parameters:

schemaManager - The SchemaManager

attribute - The associated Attribute

filterBytes - The filter bytes to parse

pos - The position in the filter bytes

Returns:

The parsed value

Throws:

ParseException - If the value can't be parsed

LdapInvalidAttributeValueException - If the value is invalid

parseAssertionValue

private static Value parseAssertionValue(SchemaManager schemaManager,
                                         byte[] filterBytes,
                                         org.apache.directory.api.util.Position pos)
                                  throws ParseException

An assertion value :

 assertionvalue = valueencoding
 valueencoding  = 0*(normal / escaped)
 normal         = UTF1SUBSET / UTFMB
 escaped        = '\' HEX HEX
 HEX            = '0'-'9' / 'A'-'F' / 'a'-'f'
 UTF1SUBSET     = %x01-27 / %x2B-5B / %x5D-7F (Everything but '\0', '*', '(', ')' and '\')
 UTFMB          = UTF2 / UTF3 / UTF4
 UTF0           = %x80-BF
 UTF2           = %xC2-DF UTF0
 UTF3           = %xE0 %xA0-BF UTF0 / %xE1-EC UTF0 UTF0 / %xED %x80-9F UTF0 / %xEE-EF UTF0 UTF0
 UTF4           = %xF0 %x90-BF UTF0 UTF0 / %xF1-F3 UTF0 UTF0 UTF0 / %xF4 %x80-8F UTF0 UTF0
 

With the specific constraints (RFC 4515):

    "The <valueencoding> rule ensures that the entire filter string is a"
    "valid UTF-8 string and provides that the octets that represent the"
    "ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII"
    "0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a"
    "backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits"
    "representing the value of the encoded octet."
 

The incoming String is already transformed from UTF-8 to unicode, so we must assume that the grammar we have to check is the following :

 assertionvalue = valueencoding
 valueencoding  = 0*(normal / escaped)
 normal         = unicodeSubset
 escaped        = '\' HEX HEX
 HEX            = '0'-'9' / 'A'-'F' / 'a'-'f'
 unicodeSubset     = %x01-27 / %x2B-5B / %x5D-FFFF
 

Parameters:

schemaManager - The SchemaManager

filterBytes - The filter bytes to parse

pos - The position in the filter bytes

Returns:

The parsed value

Throws:

ParseException - If the value can't be parsed

parseSubstring

private static ExprNode parseSubstring(SchemaManager schemaManager,
                                       String attribute,
                                       Value initial,
                                       byte[] filterBytes,
                                       org.apache.directory.api.util.Position pos)
                                throws ParseException,
                                       LdapException

Parse a substring

Parameters:

schemaManager - The SchemaManager

attribute - The filter's attribute

initial - The filter's initial part

filterBytes - The filter bytes to parse

pos - The position in the filter bytes

Returns:

the created ExprNode

Throws:

ParseException - If the Node can't be parsed

LdapException - If we met an error while parsing a filter element

parsePresenceEqOrSubstring

private static ExprNode parsePresenceEqOrSubstring(SchemaManager schemaManager,
                                                   String attribute,
                                                   byte[] filterBytes,
                                                   org.apache.directory.api.util.Position pos)
                                            throws ParseException,
                                                   LdapException

Here is the grammar to parse :

 simple    ::= '=' assertionValue
 present   ::= '=' '*'
 substring ::= '=' [initial] any [final]
 initial   ::= assertionValue
 any       ::= '*' ( assertionValue '*')*
 

As we can see, there is an ambiguity in the grammar : attr=* can be seen as a present or as a substring. As stated in the RFC :

 "Note that although both the <substring> and <present> productions in"
 "the grammar above can produce the "attr=*" construct, this construct"
 "is used only to denote a presence filter." (RFC 4515, 3)
 

We have also to consider the difference between a substring and the equality node : this last node does not contain a '*'

Parameters:

schemaManager - The SchemaManager

attribute - The filter's attribute

filterBytes - The filter bytes to parse

pos - The position in the filter bytes

Returns:

the created ExprNode

Throws:

ParseException - If the Node can't be parsed

LdapException - If we met an error while parsing a filter element

parseItem

private static ExprNode parseItem(SchemaManager schemaManager,
                                  byte[] filterBytes,
                                  org.apache.directory.api.util.Position pos,
                                  byte b,
                                  boolean relaxed)
                           throws ParseException,
                                  LdapException

Parse the following grammar :

 item           = simple / present / substring / extensible
 simple         = attr WSP* filtertype WSP* assertionvalue
 filtertype     = '=' / '~=' / '>=' / '<='
 present        = attr WSP* '=' '*'
 substring      = attr WSP* '=' WSP* [initial] any [final]
 extensible     = ( attr [":dn"] [':' oid] ":=" assertionvalue )
                  / ( [":dn"] ':' oid ":=" assertionvalue )
 matchingrule   = ":" oid
 

An item starts with an attribute or a colon.

Parameters:

schemaManager - The SchemaManager

filterBytes - The filter bytes to parse

pos - The position in the filter bytes

b - The type of item

relaxed - If the filter is analyzed in relaxed mode or not

Returns:

the created ExprNode

Throws:

ParseException - If the Node can't be parsed

LdapException - If we met an error while parsing a filter element

parseBranchNode

private static ExprNode parseBranchNode(SchemaManager schemaManager,
                                        ExprNode node,
                                        byte[] filterBytes,
                                        org.apache.directory.api.util.Position pos,
                                        boolean relaxed)
                                 throws ParseException,
                                        LdapException

Parse AND, OR and NOT nodes :

 and            = '&' filterlist
 or             = '|' filterlist
 not            = '!' filter
 filterlist     = 1*filter
 

Parameters:

schemaManager - The SchemaManager

node - The node to feed

filterBytes - The filter bytes to parse

pos - The position in the filter bytes

relaxed - If the filter is analyzed in relaxed mode or not

Returns:

the created ExprNode

Throws:

ParseException - If the Node can't be parsed

LdapException - If we met an error while parsing a filter element

parseFilterComp

private static ExprNode parseFilterComp(SchemaManager schemaManager,
                                        byte[] filterBytes,
                                        org.apache.directory.api.util.Position pos,
                                        boolean relaxed)
                                 throws ParseException,
                                        LdapException

 filtercomp     = and / or / not / item
 and            = '&' WSP* filterlist
 or             = '|' WSP* filterlist
 not            = '!' WSP* filter
 item           = simple / present / substring / extensible
 simple         = attr WSP* filtertype WSP* assertionvalue
 present        = attr WSP* EQUALS ASTERISK
 substring      = attr WSP* EQUALS WSP* [initial] any [final]
 extensible     = ( attr [dnattrs]
                    [matchingrule] COLON EQUALS assertionvalue )
                    / ( [dnattrs]
                         matchingrule COLON EQUALS assertionvalue )
 

Parameters:

schemaManager - The SchemaManager

filterBytes - The filter bytes to parse

pos - The position in the filter bytes

relaxed - If the filter is analyzed in relaxed mode or not

Returns:

the created ExprNode

Throws:

ParseException - If the Node can't be parsed

LdapException - If we met an error while parsing a filter element

parseFilterInternal

private static ExprNode parseFilterInternal(SchemaManager schemaManager,
                                            byte[] filterBytes,
                                            org.apache.directory.api.util.Position pos,
                                            boolean relaxed)
                                     throws ParseException,
                                            LdapException

Parse the grammar rule :

 filter ::= WSP* '(' WSP* filterComp WSP* ')' WSP*
 

Parameters:

schemaManager - The SchemaManager

filterBytes - The filter bytes to parse

pos - The position in the filter bytes

relaxed - If the filter is analyzed in relaxed mode or not

Returns:

the created ExprNode

Throws:

ParseException - If the Node can't be parsed

LdapException - If we met an error while parsing a filter element