| 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