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, InitialContext , InitialDirContext , and InitialLdapContext , you can supply a Hashtable parameter containing environment properties. 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, it is obtained from the applet parameters, and if not present there, from the system properties.
2. All application resource files (jndi.properties).

So, effectively, the environment 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:

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

all of the property's values are concatenated into a single colon-separated list. For other properties, only the first value found is used.

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 perform methods that obtain context objects derived from the initial context, such as Context.lookup(), the environment of the parent context is inherited.

Note that not all of the environment properties might be applicable to a context but the context is always required to record them and pass them onto 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 constructor
Context ctx = new InitialContext(env);

// See what environment properties we 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

There are several things to notice 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.

A common mistake that users make is to 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 not have any effect. In fact, you should think of the result of getEnvironment() as an immutable, read-only object and not attempt to update it at all. See the Updating Environment Properties Section for instructions on how to update a context's environment.

Environment Properties