What's in a Name?

Compound Names

A compound name is a name in single naming system. Here's an example of a compound name:

cn=homedir,cn=Jon Ruiz,ou=People

It is the string representation of an LDAP name that contains three components:

ou=People
cn=Jon Ruiz
cn=homedir

Relationship to Composite Name

When you pass a string name to a Context method, such as lookup() , the method expects a composite name. The composite name might have just one component. You may pass an LDAP string name, for instance, to lookup(). The only restriction to keep in mind is that if the string name contains characters that conflict with the composite name syntax, then those characters need to be properly escaped or quoted. For example, the compound name cn=a/b needs to be specified as cn=a\/b to prevent it from being interpreted as a composite name with two components.

When you pass a Name argument to a Context method, such as lookup() , the method can accept either a composite name or a compound name, as explained in a previous section. If you want the argument to be interpreted as a composite name, use an instance of CompositeName.

String Representations

As shown in the above example, a compound name is made up of components. The components are separated using a syntax specific for the naming system. For example, in the LDAP, components are ordered from right to left and separated by a comma character. The string representation of the following components:

ou=People
cn=Jon Ruiz
cn=homedir

is

cn=homedir,cn=Jon Ruiz,ou=People

The CompoundName Class

The CompoundName class is a convenience class for representing the structural form of a compound name. Its constructor accepts a string representation of the compound name and a set of properties that describes the naming syntax of the name. The set of properties and the CompoundName class are intended to be flexible enough to describe the syntaxes of most naming systems. However, implementors may choose to provide their own implementation of compound names that are either subclasses of CompoundName or any class that implements the Name interface.

Typically, you only use the CompoundName constructor if you are writing a service provider. As an application developer, you usually encounter compound names (either CompoundName or direct implementations of Name) when you want to parse a name from a particular naming system. Here's an example that gets the name parser for a context in a naming system and uses the parser to parse a name from that naming system:

NameParser parser = ctx.getNameParser("");
Name compoundName = parser.parse(compoundStringName);

Manipulating a Compound Name

You'll notice that NameParser.parse() returns an object that implements the Name interface. This interface is implemented by both the CompositeName and CompoundName classes. This means that you can access and update the components of a compound name in a similar way that you would a composite name. For example, here's some code that replaces the second component of a compound name and adds components to the head and tail of the name.

// Get the parser for this namespace
NameParser parser = ctx.getNameParser("");

// Parse name
Name cn = parser.parse("cn=John,ou=People,ou=Marketing");

// Remove 2nd component from head
System.out.println(cn.remove(1));          // ou=People

// Add to head (first)
System.out.println(cn.add(0, "ou=East"));  // cn=John,ou=Marketing,ou=East

// Add to tail (last)
System.out.println(cn.add("cn=HomeDir"));  // cn=HomeDir,cn=John,ou=Marketing,ou=East

Running this program produces the following output:

ou=People
cn=John,ou=Marketing,ou=East
cn=HomeDir,cn=John,ou=Marketing,ou=East

Note that the notions of head and tail are independent of the name's syntax. For example, the LDAP syntax specifies that components are ordered right to left, which means that the rightmost component is the head and the leftmost component is the tail. For such a name, when you add a component to the head ("cn=East"), it is added to the right, and when you add a component to the tail ("cn=HomeDir"), it is added to the left.

Here's the output produced by a modified version of the above example that uses Unix file name syntax instead of the LDAP syntax:

People
East/Marketing/John
East/Marketing/John/HomeDir

As Argument to Context Methods

When you pass a Name instance that is not a CompositeName to methods in the Context and DirContext interfaces, it is treated as a compound name. Here is an example that looks up an LDAP entry by using a CompoundName. It first gets a context handle into an LDAP namespace. Then it obtains a parser for that namespace by calling Context.getNameParser() , which is then used to parse an LDAP string name into a compound name. The compound name is subsequently used in the lookup() call.

// Create the initial context
Context ctx = new InitialContext(env);

// Get parser for namespace
NameParser parser = ctx.getNameParser("");

// Parse string name into compound name
Name compound = parser.parse("cn=Jon Ruiz,ou=people");

// Perform lookup using compound name
Object obj = ctx.lookup(compound);

Fully-Qualified Compound Names

Sometimes it is useful to be able to obtain the fully-qualified name of an object. For example, in the DNS, it might be useful to know a machine's fully qualified Internet name so that it could be used in Kerberos authentication or as an address for Internet mail delivery. In the LDAP, a fully qualified distinguished name might be inserted into an X.509 certificate or be given out as an email address or as part of a URL.

The use of this fully-qualified name is typically outside the scope of the JNDI. That is, once the name is obtained, it is passed to and used in other subsystems rather than fed back into one of the JNDI APIs. Furthermore, the definition of "fully qualified" is determined by the service provider and/or underlying naming/directory system.

The JNDI provides a method, Context.getNameInNamespace() , for obtaining an object's fully qualified name, relative to its own namespace. That is, the result is a name in the namespace served by the underlying naming system.

Here is an example that looks up an entry ("cn=Jon Ruiz, ou=people") and then invokes getNameInNamespace() to get its fully qualified LDAP name:

// Create the initial context
Context ctx = new InitialContext(env);

// Perform lookup 
Context jon = (Context)ctx.lookup("cn=Jon Ruiz,ou=people");

String fullname = jon.getNameInNamespace();

When you run this program, it produces the output:

cn=Jon Ruiz,ou=people,o=JNDItutorial

What's in a Name?