Environment Properties

Updating A Context's Environment

You can change a context's environment by using addToEnvironment() and removeFromEnvironment().

Following is an example that creates an initial context and then gets a context derived from that initial context (via lookup()). It then updates the environments of 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 the constructor
Context ctx = new InitialContext(env);

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

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

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

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

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

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

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

Following is the output from running the example. Notice that these updates affect only the Context instance on 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 previous example has showed, changing the environment properties of one context 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 value effectively becomes the property's value, even though the actual default value might not necessarily show up when you examine the context's properties by using getEnvironment().

Verifying the Update

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

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

Environment Properties