Directory Operations

Search Filters

In addition to specifying a search using a set of attributes, you can specify a search in the form of a search filter. A search filter is a search query expressed in the form of a logical expression. The syntax of search filters accepted by DirContext.search() is described in RFC 2254.

The following search filter specifies that the qualifying entries must have an "sn" attribute with a value of "Geisel" and a "mail" attribute with any value:

(&(sn=Geisel)(mail=*))

The following code creates a filter and default search controls, SearchControls, and uses them to perform a search. The search is equivalent to the one presented in the basic search example.

// Create the default search controls
SearchControls ctls = new SearchControls();

// Specify the search filter to match
// Ask for objects that have the attribute "sn" == "Geisel"
// and the "mail" attribute
String filter = "(&(sn=Geisel)(mail=*))";

// Search for objects using the filter
NamingEnumeration answer = ctx.search("ou=People", filter, ctls);

Running this example produces the following result.

# java SearchWithFilterRetAll
>>>cn=Ted Geisel
attribute: sn
value: Geisel
attribute: objectclass
value: top
value: person
value: organizationalPerson
value: inetOrgPerson
attribute: jpegphoto
value: [B@1dacd75e
attribute: mail
value: Ted.Geisel@JNDITutorial.com
attribute: facsimiletelephonenumber
value: +1 408 555 2329
attribute: cn
value: Ted Geisel
attribute: telephonenumber
value: +1 408 555 5252

Quick Overview of Search Filter Syntax

The search filter syntax is basically a logical expression in prefix notation (that is, the logical operator appears before its arguments). The following table lists the symbols used for creating filters.

Symbol	Description
&	conjunction (i.e., and -- all in list must be true)
|	disjunction (i.e., or -- one or more alternatives must be true)
!	negation (i.e., not -- the item being negated must not be true)
=	equality (according to the matching rule of the attribute)
~=	approximate equality (according to the matching rule of the attribute)
>=	greater than (according to the matching rule of the attribute)
<=	less than (according to the matching rule of the attribute)
=*	presence (i.e., the entry must have the attribute but its value is irrelevant)
*	wildcard (indicates zero or more characters can occur in that position); used when specifying attribute values to match
\	escape (for escaping '*', '(', or ')' when they occur inside an attribute value)

Each item in the filter is composed using an attribute identifier and either an attribute value or symbols denoting the attribute value. For example, the item "sn=Geisel" means that the "sn" attribute must have the attribute value "Geisel" and the item "mail=*" indicates that the "mail" attribute must be present.

Each item must be enclosed within a set of parentheses, as in "(sn=Geisel)". These items are composed using logical operators such as "&" (conjunction) to create logical expressions, as in "(& (sn=Geisel) (mail=*))".

Each logical expression can be further composed of other items that themselves are logical expressions, as in "(| (& (sn=Geisel) (mail=*)) (sn=L*))". This last example is requesting either entries that have both a "sn" attribute of "Geisel" and the "mail" attribute or entries whose "sn" attribute begins with the letter "L."

For a complete description of the syntax, see RFC 2254.

Returning Selected Attributes

The previous example returned all attributes associated with the entries that satisfy the specified filter. You can select the attributes to return by setting the search controls argument. You create an array of attribute identifiers that you want to include in the result and pass it to SearchControls.setReturningAttributes(). (Search controls are discussed further in the next section.) Here's an example.

// Specify the ids of the attributes to return
String[] attrIDs = {"sn", "telephonenumber", "golfhandicap", "mail"};
SearchControls ctls = new SearchControls();
ctls.setReturningAttributes(attrIDs);

This example is equivalent to the Returning Selected Attributes example in the Basic Search section. Running it produces the following results. (The entry does not have a "golfhandicap" attribute, so it is not returned.)

# java SearchWithFilter
>>>cn=Ted Geisel
attribute: sn
value: Geisel
attribute: mail
value: Ted.Geisel@JNDITutorial.com
attribute: telephonenumber
value: +1 408 555 5252

Directory Operations