Preparations

The Initial Context

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.

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 Beyond the Basics trail.

For example, if you are using the LDAP service provider from Sun Microsystems, then your code would look like the following.

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, 
	"com.sun.jndi.ldap.LdapCtxFactory");

To specify the file system service provider from Sun Microsystems, you would write code that looks like the following.

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, 
	"com.sun.jndi.fscontext.RefFSContextFactory");

You can also use system properties to specify the service provider to use. See the Beyond the Basics trail for details.

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.

For example, suppose that the program is using the LDAP service provider. This 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://ldap.wiz.com:389");
env.put(Context.SECURITY_PRINCIPAL, "joeuser");
env.put(Context.SECURITY_CREDENTIALS, "joepassword");

This tutorial uses the file system and LDAP service providers from Sun Microsystems. For the examples that use the file system, supply as the provider URL the URL corresponding to the path that you gave to the Setup program. For example, if you used the directory /tmp/tutorial in the Setup program, your code would look as follows.

env.put(Context.PROVIDER_URL, "file:/tmp/tutorial/");

The examples that use the LDAP 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. For example, if the directory is running on another machine, then you will need to replace "localhost" with the name of that machine.

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.

Preparations