Previous | Next | Trail Map | Tips for LDAP Users | 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(in the API reference documentation) and DirContext(in the API reference documentation) 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(in the API reference documentation) 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.

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 ="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 SunONE Directory Server v5.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()(in the API reference documentation)) that you get back are LDAP URLs containing the fully qualified names of the entries. If you invoke NameClassPair.isRelative()(in the API reference documentation) 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.

Previous | Next | Trail Map | Tips for LDAP Users | Miscellaneous