Searching is performed using the LDAPConnection.search methods. When you perform an LDAP search, you need to specify the following five basic parameters:
Table 1-4 Basic Parameters for LDAP Search
The search base parameter specifies the DN of the entry where you would like to begin the search, such as ou=development,o=acme.
If you would like the search to begin at the tree root pass an empty String.
NOTE:Beginning a search at the tree root is handled differently by the various LDAP server implementations. If your search doesn't return results, read the root DSE to retrieve valid naming contexts for a valid starting point.
The search scope parameter specifies the depth of the search and can be one of four values:
SCOPE_BASE. Only the entry specified as the search base is include in the search. This is used when you already know the DN of the object and you would like to read its attributes. (The read method may also be used to read the values of a single entry).
SCOPE_ONE. Objects one level below the base (but not including the base) are included in the search. If we specified o=acme as our search base, then entries in the o=acme container would be included, but not the object o=acme.
SCOPE_SUB. All objects below the base, including the base itself, are included in the search.
SCOPE_SUBORDINATESUBTREE. All subordinates of the specified base object, but does not include the base object, as the subtree scope does.
The search filter defines the entries that will be returned by the search. If you are looking for all employees with a title of engineer, the search filter would be (title=engineer).
See Search Filters for detailed information on constructing filters.
This list specifies the attributes you want returned from any found entry. By default, all attributes are returned. If you would like only the e-mail address of the entries that match your search filter, you would specify email address. To return all attributes, specify null.
NOTE:Note that operational attributes are not automatically returned by a search. You must specify any operational attributes you wish to be returned by passing them as part of the attribute list.
If you would like to return all attributes of an entry and some operational attributes, you would pass either * or ALL_USER_ATTRIBUTES with the names of the operational attributes you would like returned. When passed to a search as the attribute list parameter, the following String would return all attributes and the creatorsName operational attribute:
String[] attrList = new String[]{"*", "creatorsName"}
This specifies whether you would like to return the attributes specified by the attribute list, or the attributes and their values (specifying FALSE for the typesOnly parameter returns the attributes and their values).
The synchronous search methods return an LDAPSearchResults object, which is an enumeration of LDAPEntry objects. The next method is used to retrieve the entries and attributes from an LDAPSearchResults object.
The following is an example of a synchronous search:
String searchBase = "ou=development,o=acme";
int searchScope = LDAPConnection.SCOPE_BASE;
String searchFilter = "(title=engineer)";
LDAPSearchResults searchResults =
lc.search( searchBase,
searchScope,
searchFilter,
null,
false);
This search returns all entries with a title of engineer in the development Organizational Unit, from the acme Organization.
Note that certain pieces of the following example are left out for brevity (such as error handling and some closing brackets). See search.java in the Sample Code for a complete example.
while (searchResults.hasMore()) {
LDAPEntry nextEntry = null
nextEntry = searchResults.next();
System.out.println("\n We found "+nextEntry.getDN());
Next we will set up a second while loop to display this entry's attributes:
LDAPAttributeSet attributeSet = nextEntry.getAttributeSet();
Enumeration allAttributes = attributeSet.getAttributes();
while(allAttributes.hasMore()) {
LDAPAttribute attribute =
(LDAPAttribute)allAttributes.nextElement();
String attributeName = attribute.getName();
System.out.println("\t\t"+ attributeName);
Finally we will set up the third while loop to display the values of the found attribute. Note that this code assumes that the attribute values can be displayed as strings:
Enumeration allValues = attribute.getStringValues();
if(allValues!= null) {
while(allValues.hasMore()) {
String Value = (String) allValues.nextElement();
System.out.println("\t\t\t" + Value);
Asynchronous searches return LDAPSearchListener objects which are checked by the application for LDAPMessages.
The following is an example of an asynchronous search:
String searchBase = "ou=development,o=acme";
int searchScope = LDAPConnection.SCOPE_BASE;
String searchFilter = "(title=engineer)";
LDAPSearchListener listener =
lc.search(searchBase,
searchScope,
searchFilter,
null,
false
(LDAPSearchListener)null,
(LDAPSearchConstraints)null);
Note that instead of returning an LDAPSearchResults object the asynchronous search methods return an LDAPSearchListener. This listener is checked by the application for LDAPMessages:
LDAPMessage message;
while ((message = listener.getResponse())!= null) {
The LDAPMessage will be one of the following three types:
LDAPSearchResult: An entry returned by your search.
LDAPSearchResultReference: A continuation reference (referral) to continue your search.
LDAPResponse: A response indicating that the search is completed. If this is SUCCESS, the search completed successfully. If the result code is REFERRAL, you receive a list of URL strings. (The LDAPResponse result codes are documented in the LDAPException object in the JavaDoc).
In your code you must determine the message type and handle it appropriately. This is done using instanceof:
if (message instanceof LDAPSearchResultReference) {
When the message type has been determined you can handle the response appropriately. For a complete example of an asynchronous search see searchas.java in the Sample Code.
The LDAP search filter grammar is specified in RFC 2254 and 2251. The grammar uses ABNF notation.
filter = " (" filtercomp ") "
filtercomp = and / or / not / item
and = "&" filterlist
filterlist = 1*filter
or = "|" filterlist
filterlist = 1*filter
not = "!" filterlist
filterlist = 1*filter
item = simple / present / substring / extensible
simple = attr filtertype value
attr = name | name;binary
filtertype = equal / approx / greater / less
value = data valid for the attribute's syntax
equal = "="
approx = "~="
greater = ">="
less = "<="
present = attr "=*"
attr = name | name;binary
substing = attr "=" [initial] any [final]
attr = name | name;binary
initial = value
any = "*" *(value "*")
final = value
extensible = attr [":dn"] [":" matchingrule] ":="value
/ [":dn] ":" matchingrule ":=" value
/ matchingrule = name | OID
For additional options for the attr option, see Section 4.1.5 of RFC 2251.
For additional information on the value option, see Section 4.1.6 of RFC 2251.
IMPORTANT:Novell eDirectory does not support LDAP approximate (~=) matching or extensible matching rules.
Table 1-5 LDAP Filter Operators
The following Boolean operators can be combined with the standard operators to form more complex filters. Note that the Boolean operator syntax used is different in search filters than in the C and Java programming languages, but they are conceptually similar.
Table 1-6 LDAP Filter Boolean Operators
Operational attributes are not automatically returned in search results; they must be requested by name in the search operation. For a list of supported operational attributes in Novell eDirectory 8.5, see LDAP Operational Attributes in the LDAP and eDirectory Integration Guide. The LDAP servers in releases previous to 8.5 do not support requesting operational attributes in a search operation.