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:

1. Select the service provider of the corresponding service you want to access
2. Specify any configuration 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, your code would look like this:

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 this:

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

Another way to specify the service provider to use is with system properties. See the Beyond the Basics trail for details.

Supply the Information Needed by the Initial Context

Clients of different directories may need different information for contacting the directory. For example, you might need to specify which machine the server is running on and what information is needed to identify the user to the directory. Such information is passed onto the service provider by means of 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 the program is using the LDAP service provider, which 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 have 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, you will need to set up these environment properties accordingly. For example, if the directory is running on another machine, you would need to replace "localhost" with the name of that machine.

Create 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've 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