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:
  1. search(Name name, Attributes matchingAttrs)(in the API reference documentation)
  2. search(Name name, Attributes matchingAttrs, String[]retAttrs)(in the API reference documentation)
  3. search(Name name, String filter, SearchControls ctls)(in the API reference documentation)
  4. search(Name name, String filterExpr, Object[]filterArgs, SearchControls ctls)(in the API reference documentation)
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 is equivalent to the second form with null supplied as the retAttrs argument:
search(name, matchingAttrs, null);
The Basic Search (in the Basics trail) examples showed how to use both of these methods.

In these methods, the matchingAttrs argument is converted into an RFC 2254 string filter by creating a conjunctive expression out of its attributes. 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, 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 using the notation for encoding binary 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 Filter

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. The string filter follows the syntax specified in RFC 2254 with the exception that Unicode characters are also allowed. The use of Unicode characters is preferable to the use of encoded UTF-8 octets.

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

Using String Filter with Arguments

The fourth form of the search method allows you to construct the string filter using a filter expression filterExpr and an array of arguments filterArgs.

The filterExpr argument can contain "{n}" strings. The string filter is constructed by substituting each "{n}" string in filterExpr with the n'th element of filterArgs. Each "{n}" string may appear as an attribute name, as an attribute value, or as a component of the attribute value. (This is more precisely stated as 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 in the following way:

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

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

// Perform search
NamingEnumeration answer = ctx.search("ou=NewHires", 
    "(&(mySpecialKey={0}) (cn=*{1}))",      // filter expression
    new Object[]{key, name},                // filter arguments
    null);				    // default search controls
Two substitutions will be performed on the filter expression: one using the contents of a byte array (key), and one using a string (name). 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