Environment Properties

Customizing a Service Provider

Environment properties allow an application and its user 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, a provider resource file 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 to a forward slash character. For example, suppose that the context implementation's class name is com.sun.jndi.ldap.LdapCtx; its provider resource filename would be "com/sun/jndi/ldap/jndiprovider.properties". Whereas 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, it can be used as a deployment mechanism. For example, suppose that 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's or user's 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 JAR, then 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.

Affected Properties

Although a provider resource file can contain any property, the JNDI looks only for 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 are not added to the environment. Instead, those 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 the same property found in the environment. It then uses the resulting property as the ordered list of factories to search.

For example, suppose that the LDAP service provider, implemented by 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 event notification.
• Go to the URLs lesson to learn about the relationship between URLs and the JNDI.
• Go to the Miscellaneous lesson to read up on miscellaneous topics such as class loading and link references.

Environment Properties