![]() ![]() ![]() ![]() |
Searches |
The DirContextinterface provides the following search methods:
Each of these methods has a corresponding overloaded form that accepts a java.lang.String name instead of Name
- 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)
as the first argument.
Using Matching Attributes
The first form is equivalent to the second form with null supplied as the retAttrs argument:The Basic Searchsearch(name, matchingAttrs, null);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:
is translated into the string filter "(&(sn=Geisel)(mail=*))".sn: Geisel mail: (No value)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:
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 "*".sn: Geisel mail: *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:
is translated into the string filter "(jpegphoto=\82\12\38\4e\23\e3)".jpegphoto: 82 12 38 4e 23 e3 (byte array)Using String Filter
The Search Filterssection 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:
- byte arrays (byte[]) are encoded by encoding each byte 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. In other words, '*' 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, if you want to use special characters in the filter, you must put them in the string expression filterExpr.
- Objects that are neither String nor byte[] are converted to their string form using Object.toString(), and then the rules for String are applied.
Here's an example that demonstrates the use of this method:
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.// 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>>>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 |