Miscellaneous

Dereferencing Aliases

In the X.500, you can set a leaf entry to point to another object in the namespace. This leaf entry is referred to as an alias entry. The entry contains the distinguished name of the object that it is pointing to. When you look up an object using the alias, the alias is dereferenced so that what is returned is the object pointed to by the distinguished name contained in the alias.

You can use aliases for organizing the directory's namespace to allow old names to be used as the namespace evolves over time. Suppose, for example, that in the "o=Wiz, c=us" company the departments "ou=hardware" and "ou=software" 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, using the "java.naming.ldap.derefAliases" environment property.

Property Setting	Description
always	Always dereference aliases
never	Never dereference aliases
finding	Dereference aliases only during name resolution
searching	Dereference aliases only after name resolution

If this environment property is not set, the default is always.

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 Alias Example

This 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, 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:

• "ou=Staff" is an alias that points to "ou=People". If you list the context of "ou=Staff", 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 dereference flag as requested
    env.put("java.naming.ldap.derefAliases", args[0]);
}

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

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

Here's a summary of the results of running this program with different arguments to the command line:

Command Line Argument	Results
(none)	3 entries: cn=Jon Ruiz, cn=John Fowler, cn=J.Duke
always	3 entries: cn=Jon Ruiz, cn=John Fowler, cn=J.Duke
never	0 (because the "ou=Staff" alias is never dereferenced)
finding	2 entries: cn=Jon Ruiz, cn=John Fowler (because the "cn=Newbie" alias is never dereferenced)
searching	0 (because the "ou=Staff" alias is never dereferenced)

---

Note: The Netscape Directory Server 4.1 does not support aliases. If you run this example using that server, the results would 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 the NameClassPair.isRelative() method on them, 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