Previous | Next | Trail Map | Tips for LDAP Users | Searches

Context Search Methods

The DirContext(in the API reference documentation) interface provides the following search methods: Each of these methods has a corresponding overloaded form that accepts a java.lang.String name instead of Name(in the API reference documentation) as the first argument.

Using Matching Attributes

The first form, search(Name name, Attributes matchingAttrs), is equivalent to the second form, search(Name name, Attributes matchingAttrs, String[] retAttrs), with null supplied as the retAttrs argument: 
search(name, matchingAttrs, null);
The Basic Search (in the Basics trail) examples show how to use both of these methods.

In these methods, the matchingAttrs argument is converted into an RFC 2254 string filter that is a conjunctive expression of the attributes from matchingAttrs. For example, a matchingAttrs containing the following attributes: 

sn: Geisel
mail: (No value)
is translated into the string filter "(&(sn=Geisel)(mail=*))".

Each attribute value is treated as a literal--that is, the attribute in the directory entry is expected to contain exactly that value. Therefore, if the attribute value contains a star character ("*") or other special characters defined in RFC 2254, then the LDAP provider will apply the appropriate encoding rules. For example, a matchingAttrs containing the following attributes: 

sn: Geisel
mail: *
is translated into the string filter "(&(sn=Geisel)(mail=\2a))". In this case, the directory entry must contain a "mail" attribute whose value is the string "*".

If the attribute value is a byte array, then it is encoded by using the notation for encoding nonstring attributes, as described in RFC 2254. For example, a matchingAttrs containing the following attribute: 

jpegphoto: 82 12 38 4e 23 e3 (byte array)
is translated into the string filter "(jpegphoto=\82\12\38\4e\23\e3)".

Using String Filters

 The Search Filters (in the Basics trail) section has a quick overview of search filter syntax and contains examples of how to use the third form of the search method, search(Name name, String filter, SearchControls ctls). The string filter follows the syntax specified in RFC 2254, except that Unicode characters are also allowed. Using Unicode characters is preferable to using encoded UTF-8 octets.

For example, in the Java programming language, you can specify the Greek letter alpha as the Unicode character \u03b1. To search for an entry whose attribute value contains this character, you can use the string "\u03b1" or "\ce\b1" (with appropriate escapes for the backslash characters ("\") if you're using that character as a literal string in the Java programming language). The Unicode form is the preferred form. The LDAP service provider will translate Unicode characters into their corresponding UTF-8 representation for transmission to the server.

You need to be careful when constructing a string filter by using string concatenation and variables. In particular, you need to ensure that the resulting filter is well-formed and conveys your original intent. For example, suppose you construct a filter by concatenating the "userPassword" attribute name and a password (as recorded in the variable pw) to verify a user's password. 

"(userPassword=" + pw + ")"
If the value of pw is "*", the filter will be asking the server to verify the presence of the userPassword attribute instead of the exact match of the userPassword attribute. Furthermore, occurrence of other special characters in pw (for example, such as a closing parenthesis) might produce an invalid filter. Therefore, to ensure that pw does not violate the integrity and intent of the filter, you need to escape any of its characters that conflict with the (RFC 2254) filter syntax. Instead of doing this manually in your program, you should use the other forms of search that accept a string filter with an Object array argument or matching attributes. These forms of search automatically perform the necessary escaping of special characters.

Using String Filters with Arguments

The fourth form of the search method, search(Name name, String filterExpr, Object[] filterArgs, SearchControls ctls), allows you to construct the string filter by using a filter expression filterExpr and an array of arguments filterArgs.

The filterExpr argument can contain strings of the form "{n}", where the nth element of filterArgs replaces the occurrence of the "{n}" string in filterExpr in the resulting string filter. Each "{n}" string may appear as an attribute name, an attribute value, or a component of the attribute value. (Or more precisely, each "{n}" string may appear in place of "attr" or "value" in Section 4 from RFC 2254.)

During the substitution, the objects in filterArgs are encoded as follows.

Here's an example that demonstrates the use of this method. 

// Specify the filter arguments
byte[] key = {(byte)0x61, (byte)0x62, (byte)0x63, (byte)0x64, 
    (byte)0x65, (byte)0x66, (byte)0x67};
String name = "User";

// Perform the search
NamingEnumeration answer = ctx.search("ou=NewHires", 
    "(&(mySpecialKey={0}) (cn=*{1}))",      // Filter expression
    new Object[]{key, name},                // Filter arguments
    null);				    // Default search controls
The filter expression specifies two substitutions: the contents of the byte array key replaces "{0}" and name replaces "{1}". Note the use of the wildcard for the "cn" portion of the filter in the filter expression. Running this example produces the following output. 
>>>cn=S. User
{myspecialkey=myspecialkey: abcdefg, 
 sn=sn: User, 
 objectclass=objectclass: top, person, organizationalPerson, 
     inetOrgPerson, extensibleObject, 
 mail=mail: suser@JNDITutorial.com, 
 userpassword=userpassword: [B@1dacd79e, 
 cn=cn: S. User
}

Previous | Next | Trail Map | Tips for LDAP Users | Searches