The Java™ Tutorials
Hide TOC
Naming and Directory Operations
Trail: Java Naming and Directory Interface

Lesson: Naming and Directory Operations

You can use the JNDI to perform naming operations, including read operations and operations for updating the namespace. The following operations are described in this lesson:


Before performing any operation on a naming or directory service, you need to acquire an initial context--the starting point into the namespace. This is because all methods on naming and directory services are performed relative to some context. To get an initial context, you must follow these steps.

  1. Select the service provider of the corresponding service you want to access.
  2. Specify any configuration that the initial context needs.
  3. Call the InitialContext constructor.

Step1: Select the Service Provider for the Initial Context

You can specify the service provider to use for the initial context by creating a set of environment properties (a Hashtable) and adding the name of the service provider class to it. Environment properties are described in detail in the JNDI Tutorial.

If you are using the LDAP service provider included in the JDK, then your code would look like the following.

Hashtable<String, Object> env = new Hashtable<String, Object>();

To specify the file system service provider in the JDK, you would write code that looks like the following.

Hashtable<String, Object> env = new Hashtable>String, Object>();

You can also use system properties to specify the service provider to use. Check out the JNDI Tutorial for details.

Step2: Supply the Information Needed by the Initial Context

Clients of different directories might need various information for contacting the directory. For example, you might need to specify on which machine the server is running and what information is needed to identify the user to the directory. Such information is passed to the service provider via environment properties. The JNDI specifies some generic environment properties that service providers can use. Your service provider documentation will give details on the information required for these properties.

The LDAP provider requires that the program specify the location of the LDAP server, as well as user identity information. To provide this information, you would write code that looks as follows.

env.put(Context.PROVIDER_URL, "ldap://");
env.put(Context.SECURITY_PRINCIPAL, "joeuser");
env.put(Context.SECURITY_CREDENTIALS, "joepassword");

This tutorial uses the LDAP service provider in the JDK. The examples assume that a server has been set up on the local machine at port 389 with the root-distinguished name of "o=JNDITutorial" and that no authentication is required for updating the directory. They include the following code for setting up the environment.

env.put(Context.PROVIDER_URL, "ldap://localhost:389/o=JNDITutorial");

If you are using a directory that is set up differently, then you will need to set up these environment properties accordingly. You will need to replace "localhost" with the name of that machine. You can run these examples against any public directory servers or your own server running on a different machine. You will need to replace "localhost" with the name of that machine and replace o=JNDITutorial with the naming context that is available.

Step3: Creating the Initial Context

You are now ready to create the initial context. To do that, you pass to the InitialContext constructor the environment properties that you created previously:

Context ctx = new InitialContext(env);

Now that you have a reference to a Context object, you can begin to access the naming service.

To perform directory operations, you need to use an InitialDirContext. To do that, use one of its constructors:

DirContext ctx = new InitialDirContext(env);

This statement returns a reference to a DirContext object for performing directory operations.

Previous page: Previous Lesson
Next page: Naming Exceptions