The Ground Rules

Names

Names are discussed extensively in the What's in a Name? lesson. This section discusses in general how a service provider developer should treat the string and structured name parameters to methods in the Context interface and subinterfaces.

String Names

A string name is a composite name. Even if the context implementation that you are writing won't be supporting federation, following this rule is still a good idea so that users of your provider won't have to treat your provider differently in this respect.

Following this rule, you would write the overloads in the Context interface and subinterfaces that accept a java.lang.String name as simple wrappers around the overloads that accept a Name. As an example, here is a context implementation's definition of Context.lookup().

Object lookup(String name) throws NamingException {
    return lookup(new CompositeName(name));
}

Composite Names

A structured name is represented by an object that implements the Name interface. It can represent either a composite name or a compound name. In either case, the name parameter belongs to the caller and you should not modify it (see the Parameters and Return Values section for details).

A composite name is represented by an instance of CompositeName. If your context implementation does not support federation, then it can treat composite names in one of two ways. The simplest is for the context implementation to throw an InvalidNameException when it receives a CompositeName. However, this approach is Draconian in that it precludes the application from ever passing in a CompositeName, even if the CompositeName contains only the components that belong to the context implementation's namespace. A more compromising approach is for the context implementation to accept only CompositeNames that contain components that belong to its namespace. In this approach, the implementation extracts the components that belong to its namespace, and for components that do not belong, it throws an InvalidNameException.

If your context implementation supports federation, it should extract the components from the CompositeName that belong to its namespace. For components that do not belong, it should resolve its own components and then pass the remaining components to the nns. (More detail about this are given in the Adding Federation Support lesson.) If the implementation receives only components for its namespace, then it should process the requested operation.

Here is some pseudocode that illustrates the nonfederated case.

Object lookup(Name name) throws NamingException {
    if (name instanceof CompositeName) {
        {mine, theirs} = splitName(name);
	if (theirs.size() == 0) {
             // Find in internal tables
             return impl.get(mine);
        } else {
	     // Don't support federation
 	     throw new InvalidNameException(name.toString() + 
                " has more components than I can handle");
        }
    } else {
        // Process the compound name
        ...
    }
}

Compound Names

A compound name can be represented by any implementation of the Name interface except CompositeName or one of its subclasses. The easiest, though not the most efficient, way of making a context implementation accept a compound name is to turn it into a composite name.

Here is an example for mapping a compound name to a single-component composite name.

Object lookup(Name name) throws NamingException {
    if (name instanceof CompositeName) {
        // Process composite name
        ... 
    } else {
        // Process compound name; turn it into single-component CompositeName
        return lookup(new CompositeName().add(name.toString()));
    }
}

This is the most general solution. A context implementation typically can do this much more efficiently by using either the preparsed form (Name instance) directly or the stringified compound name. For example, an implementation might use the stringified compound name as a key to an internal hash table.

The Ground Rules