Environment Properties

A Context's Environment

You can use application resource files, the environment parameter, system properties, and applet parameters to specify environment properties. What if you use more than one of these mechanisms at the same time?

Initialization

When you use any of the constructors from the following classes, you can supply a Hashtable parameter that contains environment properties: InitialContext, InitialDirContext, and InitialLdapContext. The initial context's environment is initialized from the following two sources, in the order specified.

1. The constructor's environment parameter. If the property is one of

   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	
   

   and it does not occur in the environment parameter, then it is obtained from the applet parameters, and if not present there, from the system properties.
2. All application resource files (jndi.properties).

So the environment, effectively, is the union of the environment parameter and all application resource files, with the additional rule that some standard properties could be gotten from applet parameters or system properties.

If one of the following properties is found in both of these two sources or in more than one application resource file, then all of the property's values are concatenated into a single colon-separated list. For other properties, only the first value found is used.

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

When the constructor is called, the JNDI constructs an environment according to these rules and passes the result to the underlying service provider. When you invoke methods that obtain context objects derived from the initial context, such as Context.lookup(), the environment of the parent context is inherited.

Note that possibly not all of the environment properties will apply to a context. The context, however, is always required to record them and pass them on to any derived contexts.

Getting a Context's Environment

To obtain a context's environment, you use getEnvironment(). Here is an example.

// Initial environment with various properties
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,  
    "com.sun.jndi.fscontext.FSContextFactory");
env.put(Context.PROVIDER_URL, "file:/");
env.put(Context.OBJECT_FACTORIES, "foo.bar.ObjFactory");
env.put("foo", "bar");

// Call the constructor
Context ctx = new InitialContext(env);

// See what environment properties you have
System.out.println(ctx.getEnvironment());

When you run this example with the following application resource file in your classpath:

java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
java.naming.provider.url=ldap://localhost:389/o=jnditutorial
com.sun.jndi.ldap.netscape.schemaBugs=true

you get the following results.

com.sun.jndi.ldap.netscape.schemaBugs=true 
java.naming.factory.object=foo.bar.ObjFactory:com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
java.naming.factory.initial=com.sun.jndi.fscontext.FSContextFactory 
foo=bar 
java.naming.provider.url=file:/ 
java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory

Notice the following from this output.

• The properties found in only one source--"foo" from the environment parameter, and "com.sun.jndi.ldap.netscape.schemaBugs" from the application resource file--are in the resulting environment.
• The list-of-factories properties (e.g., "java.naming.factory.object") that occur in both sources are merged, with the one from the environment parameter occurring first in the list.
• All other properties (e.g., "java.naming.factory.initial") that occur in both sources take their values from the environment parameter.

Users often mistakenly update the result of getEnvironment() and then expect that the context's environment has been updated accordingly. Depending on the underlying provider implementation, updating the results of getEnvironment() might have no effect. In fact, you should think of the result of getEnvironment() as an immutable, read-only object and not attempt to update it. See the next section for instructions on how to update a context's environment.

Environment Properties