DeveloperNet University Home > Online Courses > LDAP extensions for JNDI

eBook (Printable PDF format)

JNDI Naming Explored

It is important to remember that JNDI is an interface rather than an implementation. This fact has some disadvantages - you need access to an existing naming service (such as an LDAP service) and you need to understand something about how it works in order to play with JNDI. On the other hand, it does allow JNDI to integrate seamlessly into an existing computing environment where an established naming service holds sway.

JNDI naming revolves around a small set of classes and a handful of operations. Let's take a look at them.

Context and Initial Context

The Context interface plays a central role in JNDI. A context represents a set of bindings within a naming service that all share the same naming convention. A Context object provides the methods for binding names to objects and unbinding names from objects, for renaming objects, and for listing the bindings.

Some naming services also provide subcontext functionality. Much like a directory in a file system, a subcontext is a context within a context. This hierarchical structure permits better organization of information. For naming services that support subcontexts, the Context class also provides methods for creating and destroying subcontexts.

JNDI performs all naming operations relative to a context. To assist in finding a place to start, the JNDI specification defines an Initial Context class. This class is instantiated with properties that define the type of naming service in use and, for naming services that provide security, the ID and password to use when connecting.

Let's take a look at Context's methods.

The Context interface also provides methods for renaming and listing bindings:.

Each of these methods has a sibling that takes a Name object instead of a String object. A Name object represents a generic name. The Name class allows a program to manipulate names without having to know as much about the specific naming service in use.

A Context Example

The example below illustrates how to connect to a naming service, list all the binding, or list a specific binding. It uses the file system service provider, which is one of the reference JNDI service-provider implementations provided by Sun. The file system service provider makes the file system look like a naming service (which it is, in many ways - filenames like /foo/bar/baz are names and are bound to objects like files and directories). The filesystem example was selected for this example, since not everyone has access to an LDAP server. However, further examples in the course will require a directory namespace such as LDAP.

import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.Binding;
import javax.naming.NamingEnumeration;
import javax.naming.NamingException;
   
import java.util.Hashtable;
   
public class Main
{
   public static void main(String [] rgstring)
   {
      try
      {
         // Create the initial context. The environment
         // information specifies the JNDI provider to use
         // and the initial URL to use (in our case, a
         // directory in URL form - file:///...).
         Hashtable hashtableEnvironment = new Hashtable();
         hashtableEnvironment.put(Context.INITIAL_FACTORY,
            "com.sun.jndi.fscontext.RefFSContextFactory" );
         hashtableEnvironment.put(Context.PROVIDER_URL, 
            rgstring[0]);
   
         Context context = new InitialContext(hashtableEnvironment);
         // If you provide no other command line arguments, 
         // list all of the names in the specified context and
         // the objects they are bound to.
   
         if(rgstring.length == 1)
         {
            NamingEnumeration namingenumeration =
            context.listBindings("");
            while(namingenumeration.hasmore())
            {
               Binding binding = 
               (Binding)namingenumeration.next();
               System.out.println(binding.getName() + 
               " " + binding.getObject());
            }
         }
         // Otherwise, list the names and binding for the
         // specified arguments.
         else
         {
            for(int i = 1; i < rgstring.length; i++)
            {
               Object object = context.lookup(rgstring[i]);
               System.out.println(rgstring[i] + " " + object);
            }
         }
         context.close();
      }
      catch(NamingException namingexception)
      {
         namingexception.printStackTrace();
      }
   }
}

The program in the listing above first creates an initial context from the specified JNDI provider (in this case, Sun's filesystem provider) and a URL specifying a local directory. If no additional command-line arguments are specified, the program lists the objects and names of every entity in the specified directory. Otherwise, it lists the objects and names of only those items specified on the command line.

Returning to Directory Services

A directory service provides a way to manage the storage and distribution of shared information. Such information can range from the e-mail address and phone numbers of a company's employees, to the IP addresses and print capabilities of a department's printers, to the configuration information for a suite of application servers. Figure 3 illustrates a generic directory service.

Figure 3: A Generic Directory Service.

A directory service manages a directory of entries. A directory entry can refer to a person, place, service, or almost any other concrete or abstract concept. An entry also has attributes associated with it; an attribute consists of a name or identifier and one or more values. These attributes describe the entry, and the exact set of attributes depends on the type of the entry. For example, the entry for an individual might have the following attributes:

Name: David Coperfield
Address: 123 Somewhere in Vegas
Email: David@magicismylife.com
Email: DCopperfield@figureitout.com

Directory services are simple databases. Like their relational cousins, many common directory services provide search and filter functionality. Instead of locating an entry point only by name, these directory services allow you to locate entries based on a set of search criteria.

Naming services and directory services are logical partners. In fact, most existing products provide both sets of functionality. Naming services provide name-to-object mapping, and directory services provide information about the objects and tools for searching for them.

There are a number of existing directory service products; LDAP is the most common. LDAP provides both naming and directory functionality. Numerous commercial implementations exist, including eDirectory. Some are even free such as OpenLDAP (http://openldap.org/).

Bringing JNDI Into the Directory Picture

JNDI directory-service support is both comprehensive and powerful. It adds advanced functions, like storing and retrieving serialized class instances, to searching and other components of the basic suite of direct functions. With this in mind, let's examine the DirContext class, which is the heart of JNDI directory services.

Working With Attributes

The DirContext class is a subclass of the Context class described last month. It provides all of the standard naming service functionality, and can also work with attributes and search for directory entries.

Let's take a look at the methods of DirContext that extend those methods provided by the Context class.

The bind() method
   
void bind (
   String stringName,
   Object object,
   Attributes attributes)

The bind() method binds a name to an object and stores the specified attributes with that entry. This operation generally tries to preserve existing attributes in cases in which that makes sense. Specifically, if attribute is null and object is an instance of the DirContext class, the resulting binding will retain the attributes originally associated with object.

The rebind() method
   
void rebind(
   String stringName,
   Object object,
   Attributes attributes)

The rebind() method binds a name to an object and stores the specified attributes with that entry. The previous binding is replaced. As is the case with bind(), this operation tries to preserve existing attributes in cases in which that would make sense.

The createSubcontext() method
   
DirContext createSubcontext(
   String stringName,
   Attributes attributes)

The createSubcontext() method creates a new subcontext and binds a name to it, and then stores the specified attributes with that entry. If attributes is null, this method works in exactly the same fashion as the like-named method of the Context class.

Let's next consider those of DirContext's methods that do not extend methods provided by the Context class, providing the tools for working with attributes instead.

The getAttributes() methods
The class provides two flavors of this method:
   
Attributes getAttributes(
   String stringName)
   
And:
   
Attributes getAttributes(
   String stringName,
   String[] rgstriongAttributeNames)

The getAttributes methods return the attributes associated with the specified entry. The Attributes class represents a collection of attributes; it contains instances of the Attribute class, which by itself represents a single attribute. The first method returns all attributes, and the second returns the attributes names in the supplied array of attribute names.

The modifyAttributes methods
modifyAttributes comes in two flavors as well:
   
void modifyAttributes(
   String stringName,
   int nOperation,
   Attributes attributes)

And:
   
void modifyAttributes(
   String stringName,
   ModificationItem[] rgmodificationitem)

The modifyatributes methods modify the attributes associated with the specified entry. The permitted operations are ADD_ATTRIBUTE, REPLACE_ATTRIBUTE, and REMOVE_ATTRIBUTE. The method modifies several attributes in the same way, while the second performs a series of modifications on one or more attributes.

As with the Context class, each of the methods above has a variant that takes a Name object rather than a String object.

Searching

In order to make use of directory service functionality, it is necessary to have some way to search the contents of a directory service. The DirContext class provides two general models by which searches may be conducted.

Searching by attribute name

There are two ways to conduct a search following this model:

NamingEnumeration search(
   String             stringName.
   Attributes             attributesToMatch)
   
And:
   
NamingEnumeration search(
   String             stringName,
   Attributes             attributesToMatch,
   String[]             rgstringAttributesToReturn)

In this first model, the search occurs within a single context for entries that contain a specific set of attributes. For the entities that match, the search retrieves either the entire set of attributes (if the search is implemented using the first block of code above) or a select set of attributes (if the search is implemented using the second).

Searching by RFC 2254 filter

There are two ways to perform this search:

NamingEnumeration search(
   Name                stringName,
   String                stringRFC2254Filter,
   SearchControls                searchcontrols)
   
And:
   
NamingEnumeration search(
   Name                stringName,
   String               stringRFC2254Filter,
   Object[]               stringRFC2254FilterArgs,
   SearchControls               searchcontrols)

In the second model, the search occurs within a context for entries that satisfy a search filter. RFC2254 (which describes a string representation for LDAP search filters, defines the format of the filter.

An instance of the SearchControls class controls key aspects of the search:

SearchControls(
   int         nSearchScope,
   long         nEntryLimit,
   int         nTimeLimit,
   String[]         rgstringAttributesToReturn,
   boolean         boolReturnObject,
   boolean         bool DereferenceLinks)

The constructor above lists all of the aspects of a search that a SearchControls instance affects. Corresponding accessors (get and set methods) also exist. The following table provides a short description of each.

With these methods in the table, they also have a variant that takes a Name object rather than a String.

Hopefully you have a solid understanding of both naming and directory services, and a general understanding of JNDI. If not, please review the Directory Concepts, LDAP, eDirectory Overview, and Overview of JNDI sections.