RFC 1960-based Filter. Filter objects can be created by calling the constructor with the desired filter string. A Filter object can be called numerous times to determine if the match argument matches the filter string that was used to create the Filter object.

The syntax of a filter string is the string representation of LDAP search filters as defined in RFC 1960: A String Representation of LDAP Search Filters (available at http://www.ietf.org/rfc/rfc1960.txt). It should be noted that RFC 2254: A String Representation of LDAP Search Filters (available at http://www.ietf.org/rfc/rfc2254.txt) supersedes RFC 1960 but only adds extensible matching and is not applicable for this API.

The string representation of an LDAP search filter is defined by the following grammar. It uses a prefix format.

  <filter> ::= '(' <filtercomp> ')'
  <filtercomp> ::= <and> | <or> | <not> | <item>
  <and> ::= '&' <filterlist>
  <or> ::= '|' <filterlist>
  <not> ::= '!' <filter>
  <filterlist> ::= <filter> | <filter> <filterlist>
  <item> ::= <simple> | <present> | <substring>
  <simple> ::= <attr> <filtertype> <value>
  <filtertype> ::= <equal> | <approx> | <greater> | <less>
  <equal> ::= '='
  <approx> ::= '˜='
  <greater> ::= '>='
  <less> ::= '<='
  <present> ::= <attr> '=*'
  <substring> ::= <attr> '=' <initial> <any> <final>
  <initial> ::= NULL | <value>
  <any> ::= '*' <starval>
  <starval> ::= NULL | <value> '*' <starval>
  <final> ::= NULL | <value>

<attr> is a string representing an attribute, or key, in the properties objects of the registered services. Attribute names are not case sensitive; that is cn and CN both refer to the same attribute. <value> is a string representing the value, or part of one, of a key in the properties objects of the registered services. If a <value> must contain one of the characters ' *' or '(' or ')', these characters should be escaped by preceding them with the backslash '\' character. Note that although both the <substring> and <present> productions can produce the 'attr=*' construct, this construct is used only to denote a presence filter.

Examples of LDAP filters are:

  "(cn=Babs Jensen)"
  "(!(cn=Tim Howes))"
  "(&(" + Constants.OBJECTCLASS + "=Person)(|(sn=Jensen)(cn=Babs J*)))"
  "(o=univ*of*mich*)"

The approximate match (~=) is implementation specific but should at least ignore case and white space differences. Optional are codes like soundex or other smart "closeness" comparisons.

Comparison of values is not straightforward. Strings are compared differently than numbers and it is possible for a key to have multiple values. Note that that keys in the match argument must always be strings. The comparison is defined by the object type of the key's value. The following rules apply for comparison:

Property Value Type	Comparison Type
String	String comparison
Integer, Long, Float, Double, Byte, Short, BigInteger, BigDecimal	numerical comparison
Character	character comparison
Boolean	equality comparisons only
[] (array)	recursively applied to values
Collection	recursively applied to values

Note: arrays of primitives are also supported.

A filter matches a key that has multiple values if it matches at least one of those values. For example,

Dictionary d = new Hashtable();
d.put("cn", new String[] {
		"a", "b", "c"
});

d will match (cn=a) and also (cn=b)

A filter component that references a key having an unrecognizable data type will evaluate to false .