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