Searches

Context Search Methods

The DirContext interface provides the following search methods:

• search(Name name, Attributes matchingAttrs)
• search(Name name, Attributes matchingAttrs, String[] retAttrs)
• search(Name name, String filter, SearchControls ctls)
• search(Name name, String filterExpr, Object[] filterArgs, SearchControls ctls)

Each of these methods has a corresponding overloaded form that accepts a java.lang.String name instead of Name 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 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 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.

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.

• Each byte in a byte array (byte[]) is encoded as a string, according to RFC 2254. For example, the array {0, 1, 10, 100} is encoded as the string "\00\01\0a\64".
• Strings are treated as literals; "*" and other special characters defined in RFC 2254 that appear in the string are encoded according to the rules in RFC 2254. For example, a string of "*" is encoded as the string "\2a". Therefore, to use special characters in the filter, you must put them in the string expression filterExpr.
• Objects that are neither a String nor a byte[] are converted to their string form via Object.toString() and then the rules for String apply.

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
}

Searches