Environment Properties

Customizing a Service Provider

Environment properties allow an application and the user of the application to customize the usage of the JNDI. You can customize a particular service provider by using a provider resource file. Like an application resource file, it contains key-value pairs presented in the properties file format (see java.util.Properties).

A provider resource file has the name:

[prefix/]jndiprovider.properties

where prefix is the package name of the provider's context implementation, with each period character converted into a slash character. For example, suppose the context implementation's class name is com.sun.jndi.ldap.LdapCtx, its provider resource file name would be com/sun/jndi/ldap/jndiprovider.properties. While a single application can use multiple application resource files, there is atmost one provider resource file per service provider. In fact, the provider resource file is typically bundled with the service provider and is loaded using the same class loader that loads the service provider.

Usage

The provider resource file serves two purposes. First, it allows the service provider to be built without being hardwired to components, such as object and state factories, and at the same times allows some defaults to be specified.

Second, the provider resource file can be used as a deployment mechanism. For example, suppose you get an LDAP service provider from a vendor. You can customize that provider by adding, for example, some object and state factories suitable for your enterprise, such as factories for accounting and employee objects. When that LDAP provider is subsequently used by your applications within your enterprise, those factories will be used automatically without the application or user having to specify the relevant properties via application resource files, system properties, applet parameters, or initial context environment parameters.

The degree to which you can manipulate a service provider's provider resource file depends on how the provider has been packaged. For example, if the provider is packaged as a Java Archive (JAR), you can supply an updated provider resource file for the provider by first extracting the contents of the JAR and then repackaging it with the updated provider resource file. Note that this procedure is not recommended for the service providers that are packaged in the Java 2 SDK/JRE, Standard Edition, v1.3. For those service providers, you should not try to update their provider resource files. Instead use application resource files as described previously in this lesson.

Properties that are Affected

Although a provider resource file can contain any property, the JNDI looks for only the following from a provider resource file:

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

Unlike the contents of an application resource file, the contents of a provider resource file is not added to the environment. Instead, a provider resource file's contents augment the value of the environment supplied to the following methods:

• NamingManager.getObjectInstance(Object, Name, Context, Hashtable)
• DirectoryManager.getObjectInstance(Object, Name, Context, Hashtable, Attributes)
• NamingManager.getStateToBind(Object, Name, Context, Hashtable)
• DirectoryManager.getStateToBind(Object, Name, Context, Hashtable, Attributes)
• ControlFactory.getControlInstance(Control, Context, Hashtable)

When a service provider calls one of these methods, it supplies an instance of the Context from which the method is being called and the context's environment. The JNDI uses the context's class loader to find the provider resource file and appends the value of the property (relevant for the method) to that found in the environment. It then uses the resulting property as the ordered list of factories to search.

For example, suppose the LDAP service provider, implemented using the class com.sun.jndi.ldap.LdapCtx, calls DirectoryManager.getObjectInstance(). The JNDI will find the value of the java.naming.factory.object property from the com/sun/jndi/ldap/jndiprovider.properties file and append that to the value of the java.naming.factory.object property found in the environment parameter (Hashtable). The JNDI will then use this list of factories to find an object factory that returns a non-null answer.

A service provider is free to access the provider resource file for other properties, but that behavior is provider-specific.

Environment Properties: End of Lesson

What's next? Now you can:

• Continue on in this trail to learn about URLs.
• Go to the Federation lesson to learn about federation.
• Go to the Miscellaneous lesson to read up on miscellaneous topics such as class loading and link references.

Environment Properties