Setting the JNDI Environment Properties

There are three main ways to set the environment properties for JNDI:

Use an environment object in the InitialContext constructor
Use system properties
Use resource files

Resource files allow you to externally define environment properties using files that follow the java.util.Properties format. This prevents you from having to change your source code when environment properties are changed. This usually is the best approach, but not all situations are the same, so you might need to use one of the alternative methods . The following sections describe each of the approaches.

Using a `Hashtable` to Set Environment Properties

The first method allows the environment properties to be set inside your JNDI client application by passing a java.util.Hashtable into the constructor of the InitialContext . The following code fragment shows an example of setting the environment properties for locating the JNDI service:

 Hashtable env = new Hashtable();  env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");  env.put(Context.PROVIDER_URL, "ldap://localhost:389/o=JNDITutorial");  Context ctx = new InitialContext(env);

This approach has the down side of being explicitly implemented within the client application code. If you wanted to change where the JNDI service was located or which initial context factory you were using, you would have to modify and recompile your source code. That's why this approach is the least desirable.

Using System Properties

Another way to specify JNDI environment properties is to provide them through the system properties when starting a Java application. Java allows you to specify system properties on the command line with a -D option. You specify properties on the command line using a key=value syntax. JNDI will only look for the following environment properties from the command line:

java.naming.factory.initial
java.naming.factory.object
java.naming.factory.state
java.naming.factory.control
java.naming.factory.url.pkgs
java.naming.provider.url
java.naming.dns.url

You can set the JNDI environment properties using the command line like this:

 # java -Djava.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory        -Djava.naming.provider.url=ldap://localhost:389/o=JNDITutorial

Using system properties to configure your JNDI applications provides a way to set the environment properties outside your source code. However, you must worry about typing all the properties in on the command line. Although you could create startup scripts to do this for you, you would need to add the system properties for all your JNDI client applications. You would also need to change each script when the JNDI configuration changed. Setting JNDI environment properties with the command line is somewhat better than putting them in your source code, but we can still do better. The next section talks about using resource files.

Tip

If you are using JNDI from an applet, it's best to specify the environment properties in the applet using normal applet parameters. Here's an example:

 <param  name=java.naming.factory.initial  value=com.sun.jndi.ldap.LdapCtxFactory>  <param  name=java.naming.provider.url  value= ldap://localhost:389/o=JNDITutorial >

This is because applets generally are not allowed to read system properties or system files because of the tight security restrictions that are placed on them.

Using Resource Files

The third way of setting JNDI environment properties is to use a resource file. Resource files are probably the best approach to setting the properties, because they completely decouple the application from the JNDI properties. A resource file is a file in the java.util.Properties format that contains a list of key=value pairs. Here is an example of a JNDI resource file:

 java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory  java.naming.provider.url=ldap://localhost:389/o=JNDITutorial

The key is the name of the environment property and the value is a string in the format defined for that property. The format of the value may be provider-dependent, so be sure to check the documentation for your JNDI provider. There are two types of resource files:

Provider resource files
Application resource files

The service provider and JNDI class libraries locate and read the resource files automatically, and the environment properties that are contained within these files become available to the environment without having to load them programmatically. This is why this method is the most flexible and gives you the most portability. How this is done will be covered later in this chapter.

Provider Resource Files

Each JNDI service provider might have an optional resource file that lists properties specific to that provider. The name of this resource is typically

 [  prefix  /]jndiprovider.properties

where prefix is the package name of the provider's context implementation.

For example, suppose a service provider defines a context implementation with class name com.sun.jndi.ldap.LdapCtx . The provider resource file for this provider would be named com/sun/jndi/ldap/jndiprovider.properties . If the class is not in a package, the resource's name is simply jndiprovider.properties .

A provider can put properties that are specific to its service within the provider resource file, but it can also override the standard environment properties. The following standard JNDI environment properties can be set in the provider resource file and override any value already set for the property:

java.naming.factory.object
java.naming.factory.url.pkgs
java.naming.factory.state
java.naming.factory.control

The JNDI library will consult the provider resource file when determining the values of these properties. The provider might not allow you to set certain properties here. Check the provider's documentation to determine which properties can be set in the provider specific resource file.

Application Resource Files

Application resource files are text files that are in the java.util.Properties format that can specify additional key=value pairs that are loaded and made available to the environment of the InitialContext . These files can be located within the application classpath and will be automatically picked up. The JNDI class libraries will locate these files using one of the getResources methods defined in the java.lang.ClassLoader class.

Listing 4.1 shows a sample jndi.properties resource file.

Listing 4.1 A Sample `jndi.properties` File

 java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory  java.naming.provider.url=ldap://localhost:389/o=JNDITutorial

JNDI will automatically read the jndi.properties resource files from the system classpath and <JAVA_HOME>/lib , where JAVA_HOME is the directory that contains your JRE (Java Runtime Environment).

Note

If you are using Java 1.1 or earlier, JNDI will not search the system classpath for the jndi.properties resource file. However, you can put the application resource file in the <JAVA_HOME> /lib directory and have JNDI find the properties.

You can have multiple jndi.properties files defined in several locations, and JNDI will just use the first value for a property that it finds or concatenate them together, if the property can have multiple values. JNDI then makes these properties from the application resource files available to the service providers and other components that need to use them.

Caution

Because the system will load the files automatically, application resource files should be considered world-readable and should not contain sensitive information, such as clear-text passwords.

When the jndi.properties file is located correctly based on the version of Java that you are using, you can create an InitialContext object without supplying the environment properties in the constructor. You can now replace the code that used a Hashtable of environment properties and passed them to the constructor of the InitialContext with just the call to the default no-argument constructor of the InitialContext . The following line shows what this would look like:

 Context ctx = new InitialContext();

Notice that we didn't have to provide any environment properties to the InitialContext . They would be picked up from the jndi.properties resource file. This makes your code much more portable. The use of application resource files to specify any JNDI environment properties allows the JNDI to be configured with minimal programmatic setup. You don't have to change any source code when any of the environment properties need to be modified. You can also configure the JNDI for all applications and applets that use the same Java interpreter and keep the properties in one place. That way, you have to make changes in only a single location.

If you use application resource files with applets, you must remember to grant your applet permission to read all the application resource files.

Search Algorithm for Finding Resource Files

When a client application attempts to connect to a JNDI naming service, there is a particular algorithm that the JNDI libraries will use to locate environment properties. First, if any environment properties are passed in the constructor of the InitialContext , they will be used to initialize the context's environment. Second, system properties will be added to the JNDI environment. If an applet is being used, any applet parameters will be added next. Finally, the environment properties from any resource files that have been included will be added.