Previous | Next | Trail Map | The Basics | Directory Operations

Search Scope

The default SearchControls(in the API reference documentation) specifies that the search is to be performed in the named context ( SearchControls.ONELEVEL_SCOPE(in the API reference documentation)). This default is used in the examples in the Search Filter section.

In addition to this default, you can also specify that the search be performed in the entire subtree, or that the search be performed only in the named object.

Subtree Search

Searching the entire subtree means that the named object and all of its descendants are searched. To make the search behave this way, pass SearchControls.SUBTREE_SCOPE(in the API reference documentation) to the SearchControls.setSearchScope()(in the API reference documentation) method as follows:

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

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

// Search subtree for objects using filter
NamingEnumeration answer = ctx.search("", filter, ctls);
This example searches the context ctx's subtree for entries that satisfy the specified filter. It found the entry "cn= Ted Geisel, ou=People" in this subtree that satisfies the filter.
# java SearchSubtree
>>>cn=Ted Geisel, ou=People
attribute: sn
value: Geisel
attribute: mail
value: Ted.Geisel@JNDITutorial.com
attribute: telephonenumber
value: +1 408 555 5252

Search the Object

You can also search the named object. This is useful, for example, if you want to test whether the named object satisfies a search filter. To search the named object, pass SearchControls.OBJECT_SCOPE(in the API reference documentation) to setSearchScope():

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

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

// Search subtree for objects using filter
NamingEnumeration answer = 
    ctx.search("cn=Ted Geisel, ou=People", filter, ctls);
This example tests whether the object "cn=Ted Geisel, ou=People" satisfies the given filter:
# java SearchObject
>>>
attribute: sn
value: Geisel
attribute: mail
value: Ted.Geisel@JNDITutorial.com
attribute: telephonenumber
value: +1 408 555 5252
It found one answer and printed it. Notice that the name of the result is the empty string, because the name of the object is always named relative to the context of the search (in this case, "cn=Ted Geisel, ou=People").


Previous | Next | Trail Map | The Basics | Directory Operations