6 Configuration

6.1 Environment Properties

Some JNDI applications need a way to communicate various preferences and information that define the environment in which naming and directory services are accessed. For example, an application might need to specify the level of security for accessing a directory service. Or, when directory and naming services are distributed, the source of information is in more than one place--replicas, master, caches, etc. An application might want to access information from the authoritative source and needs to indicate this information to the JNDI system.

To address these requirements, JNDI defines a number of properties that developers and users can use to provide configuration information to the JNDI system. These are called environment properties .

There are different types of environment properties:

Standard JNDI environment properties. These properties are defined by JNDI and are common across all service providers. They are defined in relatively generic terms. For example, the property "java.naming.security.principal" is used to specify the security principal for authentication to the naming service. Individual service providers map these environment properties to an interpretation appropriate for their service. These properties have the prefix "java.naming.". contains a list of standard JNDI environment properties. The Context interface defines constants for most of these environment property names.
Service-specific environment properties. These properties are common across all service providers that implement a particular service or protocol. They have the prefix "java.naming. service. ", where service is the name of the service. For example, the prefix "java.naming.ldap." is used for LDAP-specific environment properties.
Feature-specific environment properties. These properties are common across all service providers that support a particular feature. They have the prefix "java.naming. feature .", where feature is the name of the feature. For example, the prefix "java.naming.security.sasl." is used for SASL-specific environment properties.
Provider-specific environment properties. These properties only apply to a particular service provider. They should have a prefix that reflects this uniqueness. A common practice is to use the package name of the service provider as the prefix. For example, since Sun's LDAP provider is primarily contained in the package com.sun.jndi.ldap , properties specific to Sun's LDAP provider have the prefix "com.sun.jndi.ldap.".

See the following section for security-related considerations when using environment properties.

Although the support for environment properties is rather extensive, it is important to note that an application typically does not need to deal with them, or only needs to set one or two properties. Most properties have reasonable defaults and only need to be adjusted when the application has special requirements.

6.2 Context Environment

A context's environment is represented as a java.util.Hashtable or any of its subclasses (e.g., java.util.Properties 1 ). It is typically specified using an argument to the InitialContext , InitialDirContext , or InitialLdapContext constructors, and augmented with data from other sources (as discussed in the rest of this section). They are inherited from the parent context as context methods proceed from one context to the next. For example, the following code creates an environment consisting of two security-related properties and creates an initial context using that environment.

Hashtable env = new Hashtable();
env.put(Context.SECURITY_PRINCIPAL, "jsmith");
env.put(Context.SECURITY_CREDENTIALS, "xxxxxxx");
Context ctx = new InitialContext(env);

Contexts that are looked up or otherwise derived from this initial context will have these two properties in their environment.

A context's environment can be examined using Context.getEnvironment() .

Not all environment properties are meaningful to all contexts. Those that are not meaningful are ignored by the context but inherited by derived contexts (because they might be meaningful, for instance, to federated contexts).

6.3 Resource Files

A JNDI resource file is a file in the properties file format (see java.util.Properties ). The file contains a list of key/value pairs. The key is the name of the property (e.g., "java.naming.factory.object") and the value is a string in the format defined for that property. Here is an example of a JNDI resource file:

java.naming.factory.object=com.wiz.jndi.AttrsToCorba:com.wiz.jndi.ToPerson
java.naming.factory.state=com.wiz.jndi.CorbaToAttrs:com.wiz.jndi.FromPerson
java.naming.factory.control=com.wiz.jndi.MyResponseControlFactory

There are two kinds of JNDI resource files: application and provider.

Application Resource Files

When an application is deployed, it will generally have several codebase directories and JARs in its classpath. Similarly, when an applet is deployed, it will have a codebase and archives specifying where to find the applet's classes. JNDI locates all application resource files named jndi.properties in the classpath. In addition, if the file $JAVA_HOME/lib/jndi.properties exists and is readable, JNDI treats it as an additional application resource file. ( $JAVA_HOME is the directory named by the java.home system property.) All of the properties contained in these files are placed into the environment of the initial context. This environment is then inherited by other contexts.

For each property found in more than one application resource file, JNDI uses the first value found or, in a few cases where it makes sense to do so, it concatenates all of the values. For example, if the java.naming.factory.object property is found in three jndi.properties resource files, the list of object factories is a concatenation of the property values from all three files. Using this scheme, each deployable component is responsible for listing the factories that it exports. JNDI automatically collects and uses all of these export lists when searching for factory classes.

Application resource files are available beginning with the Java Platform, except that the file in $JAVA_HOME/lib can be used on all Java platforms.

Provider Resource Files

Each service provider has an optional resource file that contains properties specific to that provider. The name of this resource is:

[prefix/]jndiprovider.properties

where prefix is the package name of the provider's context implementation(s), with each period (".") converted to a slash ("/").

The JNDI library will consult the provider resource file when determining the values of certain properties. Properties other than these can be set in the provider resource file at the discretion of the service provider. The service provider's documentation should clearly state which properties are allowed.

6.4 Application/Applet-scope Standard JNDI Properties

Certain standard JNDI properties can alternately be set in the Java runtime's system properties, or in an applet's parameter list. These properties are:

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

For JNDI to access an applet's parameters, the applet code must set the java.naming.applet environment property to an instance of the applet ( java.applet.Applet ).

When these properties are set as system properties or applet parameters, they affect all of the application's/applet's contexts.

6.6 Modifications to the Environment

A context's environment can be changed using the addToEnvironment() and removeFromEnvironment() methods:

public interface Context {
        public Object addToEnvironment(String propName, Object val)
                throws NamingException;
        public Object removeFromEnvironment(String propName)
                throws NamingException;
        ...
}

Not all environment properties are meaningful to all contexts. Changes to those that are not meaningful are still recorded and passed onto derived contexts.

Scope

Changing a property using the addToEnvironment() or removeFromEnvironment() methods affects the context instance on which the method is invoked. For example, if you specify new credentials for a context to use, subsequent methods invoked on that context that require communication with the server will use those new credentials (perhaps internally by first creating a new connection to the server). These updated environment properties are inherited by context instances that are subsequently derived from the affected context instance, but do not otherwise affect other context instances that were in existence prior to the update.

Timeliness

When a change is made to the environment properties, there is no requirement that the change be verified and acted upon at the time addToEnvironment() or removeFromEnvironment() is invoked. The only requirement is that the change (or changes) be effective the next time an operation that uses that property is invoked.

Defaults

For some environment properties, JNDI defines defaults (see Appendix A). For others, the default might be determined by the service provider or a group of service providers. If a context's environment does not have a particular property, the context behaves as if its environment has that property with its default value.

When a property is removed from a context's environment, the context assumes the default behavior specified for that property. This does not necessarily mean that the default value must be recorded as the property's value. The removal may also be indicated by the absence of the property from the context's environment.

Acceptable Values

Some environment properties have a fixed set of acceptable values while others have values that must follow a particular syntax. If an unacceptable value is presented, a property-specific exception will be thrown (for example, ConfigurationException , IllegalArgumentException , or AuthenticationNotSupportedException ). In some cases, it might be reasonable for the service provider to accept additional values than those specified, in which case, those values should be documented.

1. Note that if you use Properties, only the top-level properties are consulted--its defaults are not consulted--because Hashtable.get() is used when retrieving entries from the environment. See java.util.Properties for details.

6. Configuration