| 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