Environment Properties

Updating Environment Properties

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

Here is an example that creates an initial context and then gets a context derived from that initial context (via lookup()). It then makes updates to the initial context and the derived context.

// 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);

// Get child context
Context child = (Context)ctx.lookup("tmp");

// See what properties initial context has
System.out.println(ctx.getEnvironment());

// Replace foo in parent
ctx.addToEnvironment("foo", "baz");
	  
// Add a new property to parent
ctx.addToEnvironment("com.wiz.jndi.wizProp", "wizards");

// Remove an attribute from parent
ctx.removeFromEnvironment(Context.OBJECT_FACTORIES);

// Remote property from child
child.removeFromEnvironment(Context.PROVIDER_URL);

// See what environment properties we have after updates
System.out.println(">>>>> Parent context: ");
System.out.println(ctx.getEnvironment());

// See what environment properties child has after updates
System.out.println(">>>>> Child context: ");
System.out.println(child.getEnvironment());

Here is the output from running the example. Notice that these updates only affect the context instance upon which they are performed.

{
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
}

>>>>> Parent context: 
{
com.sun.jndi.ldap.netscape.schemaBugs=true, 
com.wiz.jndi.wizProp=wizards, 
java.naming.factory.initial=com.sun.jndi.fscontext.FSContextFactory, 
foo=baz, 
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
}

>>>>> Child context: 
{
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.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person, 
java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
}

Scope of Changes

As the above example has shown, when you change the environment properties of one context, it does not affect any of its derived contexts. However, contexts that are derived in the future from this context will inherit the updated environment.

Defaults

Some environment properties have defaults. For example, an implementation might by default ignore referrals unless the java.naming.referral environment property has been set to throw or follow. When such a property is removed by using removeFromEnvironment(), the default effectively becomes the property's value, even though the actually default value might not necessary show up when you examine the context's properties using getEnvironment().

Verifying the Update

After you have updated a context's environment, you can verify the update immediately by using getEnvironment(). However, oftentimes an environment property represents a behavioral aspect of the context, for example, what credentials to use when logging into the server. In such cases, these is no guarantee that just because the property has been updated, that the context has verified the correctness and applicability of the property because that might require server interaction. The next time that the context needs to use the property, the verification will happen and a failure might be indicated at that time.

For example, suppose you used addToEnvironment() three times to update the principal's identity, credentials, and authentication type. Suppose also that you supplied the wrong credentials. The next time you invoke a method that requires authentication on the context, the underlying service provider will attempt to authenticate using the updated properties, but the authentication will fail because of the wrong credentials. At that time, you will get an AuthenticationException.

Environment Properties