Figure 5.10 Results of using a filter.
| Previous | Table of Contents | Next |
This code creates an initial context on our LDAP server, then creates a filter string. The string is passed as a parameter to the search method, which searches the named context (people) relative to the initial context for objects meeting the filter criteria. Then the resulting NamingEnumeration is processed and the results are printed. The output resembles Figure 5.10, which shows that two people fit the filter criteria. Both have names starting with E, and both have an account with a balance greater than $1,005 in the server.
All of the search examples thus far have ignored performance issues because the example LDAP server has very few records. Consider what would happen if a search was performed for all records in the U.S. phone directory. Obviously, limiting the search results is important. The next section discusses how to deal with this and other performance issues within JNDI.
Figure 5.10 Results of using a filter.
Recall that in the last example, the search method required an additional parameter that was set to null. This parameter is a SearchControls object. SearchControls allows you to fine-tune the performance of your search. The SearchControls methods are listed in Table 5.12.
| Table 5.12 SearchControls Methods | |
| METHOD | USE |
|---|---|
| SearchControls() | This constructor creates an instance of SearchControls with defaults set to search one level, with no maximum return limit for search results, with no time limit for a search, that returns all attributes associated with objects that satisfy the search filter, and returns the name and class but not the named object itself. Links are not dereferenced during search. |
| SearchControls(int scope, long climit, int tlimit, String[] attrs, boolean retobj, boolean deref) | This constructor creates an instance of SearchControls with scope set to OBJECT_SCOPE, ONELEVEL_SCOPE, or SUBTREE_SCOPE. The parameter tlimit sets the maximum number of milliseconds to wait before returning if the search is taking awhile. If tlimit is set to 0, the search will wait indefinitely, if necessary. The parameter deref specifies that the search should dereference links during search if deref is set to true. The parameter climit specifies the maximum number of entries to return from the search. If climit is set to 0, return all entries that satisfy the filter. The parameter retobj specifies that the result should return the object bound to the name of the entry if retobj is set to true. The parameter attrs contains the identifiers of the attributes to return. If attrs is null, all attributes are returned. If attrs is not null but contains no identifiers, no attributes will be returned. |
| long getCountLimit() | Returns the maximum number of entries that will be returned as a result of the search. |
| boolean getDerefLinkFlag() | Returns true if links will be dereferenced during the search. |
| String[] getReturningAttributes() | Returns the array of attributes that will be returned as part of the search. |
| boolean getReturningObjFlag() | Returns true if object values will be returned as part of the result. |
| int getSearchScope() | Returns the search scope for these search controls. The search scope is OBJECT_SCOPE, ONELEVEL_SCOPE, or SUBTREE_SCOPE. |
| int getTimeLimit() | Returns the maximum time limit in milliseconds that the search controls will wait for results. |
| void setCountLimit(long limit) | Sets the maximum number of entries to be returned as a result of the search. |
| void setDerefLinkFlag(boolean on) | Sets the search controls such that if on is true, the links will be dereferenced during the search. |
| void setReturningAttributes(String[] attrs) | Specifies the attributes that will be returned as part of the search. |
| void setReturningObjFlag(boolean on) | Sets the search controls such that if on is true, the object values will be returned as part of the search results. |
| void setSearchScope(int scope) | Sets the search scope to one OBJECT_SCOPE, ONELEVEL_SCOPE, or SUBTREE_SCOPE. |
| void setTimeLimit(int ms) | Sets the maximum time limit in milliseconds that the search controls will wait for results. |
Using the SearchControls, you can limit the number of objects returned from the search.
NOTE: search(name, filter, null) is equivalent to search(name, filter, new SearchControls()).
The default SearchControls constructor sets the following values:
A SearchControls object is not synchronized, so multiple threads trying to access and modify a single SearchControls instance should lock the object. Table 5.13 lists the values stored when a SearchControls instance is serialized.
The SearchControls can be used to control the attributes returned as well as the objects returned.
Return Selected Attributes Using SearchControls
The search methods of DirContext in Table 5.6 that take a SearchControls parameter do not accept an attribute list. In cases in which you are using SearchControls, you do not need that extra parameter. The SearchControls method setReturningAttributes allows you to specify an array of attribute names. This array specifies which attributes will be returned as a result of the search.
NOTE: If not all of the attributes listed in the returning attributes array are available, the available attributes are returned. The purpose of the setReturningAttributes method is to limit the scope of the results.
Here is what the code for retrieving a set of attributes using a SearchControls may look like:
import javax.naming.*;
import javax.naming.directory.*;
import java.util.Hashtable;
public class SearchControlsExample
{
| Previous | Table of Contents | Next |