| Miscellaneous

## Dereferencing Aliases

> In the X.500, you can set a leaf entry to point to another object in the namespace. Called an alias entry, it contains the DN of the object to which it is pointing. When you look up an object by using the alias, the alias is dereferenced so that what is returned is the object pointed to by the alias's DN.

> You can use aliases to organize the directory's namespace so that as the namespace evolves, old names may be used. Suppose, for example, that in the `"o=Wiz, c=us"` company, the departments `"ou=hardware"` and `"ou=software"` are merged into `"ou=engineering"`. You can move the contents of `"ou=hardware"` and `"ou=software"` to `"ou=engineering"`, and change the entries `"ou=hardware"` and `"ou=software"` into alias entries that point to `"ou=engineering"`.

> In the LDAP, aliases are supported in the same way as in the X.500.

> When you use Sun's LDAP service provider, you can control how aliases are dereferenced in one of four ways, by using the `"java.naming.ldap.derefAliases"` environment property, as shown in the following table. If this environment property is not set, then the default is `"always"`.

> Property Setting | Description
> --- | ---
> `always` | Always dereference aliases.
> `never` | Never dereferences aliases.
> `finding` | Dereferences aliases only during name resolution.
> `searching` | Dereferences aliases only after name resolution.

> In the LDAP, these four modes of alias dereferencing affect only the "search" operations. No dereferencing is done for the update operations "modify," "add," and "delete."

> Similarly, in the JNDI, no dereferencing is done for the update methods in the `Context` and `DirContext` interfaces. The `"java.naming.ldap.derefAliases"` environment property affects all methods that read from the directory.

> Note also that the "dereference links" flag in the `SearchControls` class is not related to aliases.

> #### Dereferencing Aliases Example

> The following example demonstrates how the `"java.naming.ldap.derefAliases"` environment property affects the "search" operation. It accepts as a command-line argument one of the four settings for `"java.naming.ldap.derefAliases"`. If no argument has been specified, then the environment property is not set (which is equivalent to setting it to `"always"`).

> For this example, the directory has been set up with two aliases, as follows.

> - `"ou=Staff"` is an alias that points to `"ou=People"`. If you list the context of `"ou=Staff"`, then you will see the contents of the `"ou=People"` context.
> - `"cn=Newbie, ou=People"` is an alias that points to the `"cn=J. Duke, ou=NewHires"` entry.

> After setting the environment property, the example performs a search on the `"ou=Staff"` context for all entries whose `"cn"` attribute begins with "J." Here's the code fragment that sets the environment property and performs the search.

> >     if (args.length > 0) {
> >         // Set the dereference flag as requested
> >         env.put("java.naming.ldap.derefAliases", args[0]);
> >     }

> >     // Create the initial context
> >     DirContext ctx = new InitialDirContext(env);

> >     // Perform the search
> >     NamingEnumeration answer = ctx.search("ou=Staff", "(cn=J*)", null);

> The following table summarizes the results of running this program with different arguments to the command line.

> Command Line Argument | Results
> --- | ---
> (none) | Three entries: `"cn=Jon Ruiz"`, `"cn=John Fowler"`, `"cn=J.Duke"`
> `always` | Three entries: `"cn=Jon Ruiz"`, `"cn=John Fowler"`, `"cn=J.Duke"`
> `never` | Zero (because the `"ou=Staff"` alias is never dereferenced)
> `finding` | Two entries: `"cn=Jon Ruiz"` and `"cn=John Fowler"` (because the `"cn=Newbie"` alias is never dereferenced)
> `searching` | Zero (because the `"ou=Staff"` alias is never dereferenced)

> > Note: The Netscape Directory Server v4.1 does not support aliases. If you run this example using that server, then the results will be as if the setting is `"never"`.

> When you run these examples, the names of the entries ( `NameClassPair.getName()`) that you get back are LDAP URLs containing the fully qualified names of the entries. If you invoke `NameClassPair.isRelative()` on them, then the method returns `false`. This is because when the alias is followed, it reaches another part of the namespace that is no longer named relative to the `"ou=Staff"` context.

| Miscellaneous