/*
 * @(#)Context.java	1.14 06/07/19
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.naming;

import java.util.Hashtable;

/**
 * This interface represents a naming context, which
 * consists of a set of name-to-object bindings.
 * It contains methods for examining and updating these bindings.
 * <p>
 * <h4>Names</h4>
 * Each name passed as an argument to a <tt>Context</tt> method is relative
 * to that context.  The empty name is used to name the context itself.
 * A name parameter may never be null.
 * <p>
 * Most of the methods have overloaded versions with one taking a
 * <code>Name</code> parameter and one taking a <code>String</code>.
 * These overloaded versions are equivalent in that if
 * the <code>Name</code> and <code>String</code> parameters are just
 * different representations of the same name, then the overloaded
 * versions of the same methods behave the same.
 * In the method descriptions below, only one version is fully documented.
 * The second version instead has a link to the first:  the same
 * documentation applies to both.
 * <p>
 * For systems that support federation, <tt>String</tt> name arguments to
 * <tt>Context</tt> methods are composite names. Name arguments that are
 * instances of <tt>CompositeName</tt> are treated as composite names,
 * while <tt>Name</tt> arguments that are not instances of
 * <tt>CompositeName</tt> are treated as compound names (which might be
 * instances of <tt>CompoundName</tt> or other implementations of compound
 * names). This allows the results of <tt>NameParser.parse()</tt> to be used as
 * arguments to the <tt>Context</tt> methods.
 * Prior to JNDI 1.2, all name arguments were treated as composite names.
 *<p>
 * Furthermore, for systems that support federation, all names returned
 * in a <tt>NamingEnumeration</tt>
 * from <tt>list()</tt> and <tt>listBindings()</tt> are composite names
 * represented as strings.
 * See <tt>CompositeName</tt> for the string syntax of names.
 *<p>
 * For systems that do not support federation, the name arguments (in
 * either <tt>Name</tt> or <tt>String</tt> forms) and the names returned in
 * <tt>NamingEnumeration</tt> may be names in their own namespace rather than
 * names in a composite namespace, at the discretion of the service
 * provider.
 *<p>
 *<h4>Exceptions</h4>
 * All the methods in this interface can throw a <tt>NamingException</tt> or
 * any of its subclasses. See <tt>NamingException</tt> and their subclasses
 * for details on each exception.
 *<p>
 *<h4>Concurrent Access</h4>
 * A Context instance is not guaranteed to be synchronized against
 * concurrent access by multiple threads.  Threads that need to access
 * a single Context instance concurrently should synchronize amongst
 * themselves and provide the necessary locking.  Multiple threads
 * each manipulating a different Context instance need not
 * synchronize.  Note that the {@link #lookup(Name) <tt>lookup</tt>}
 * method, when passed an empty name, will return a new Context instance
 * representing the same naming context.
 *<p>
 * For purposes of concurrency control,
 * a Context operation that returns a <tt>NamingEnumeration</tt> is
 * not considered to have completed while the enumeration is still in
 * use, or while any referrals generated by that operation are still
 * being followed.
 *
 *<p>
 *<h4>Parameters</h4>
 * A <tt>Name</tt> parameter passed to any method of the
 * <tt>Context</tt> interface or one of its subinterfaces
 * will not be modified by the service provider.
 * The service provider may keep a reference to it
 * for the duration of the operation, including any enumeration of the
 * method's results and the processing of any referrals generated.
 * The caller should not modify the object during this time.
 * A <tt>Name</tt> returned by any such method is owned by the caller.
 * The caller may subsequently modify it; the service provider may not.
 *
 *<p>
 *<h4>Environment Properties</h4>
 *<p>
 * JNDI applications need a way to communicate various preferences
 * and properties that define the environment in which naming and
 * directory services are accessed. For example, a context might
 * require specification of security credentials in order to access
 * the service. Another context might require that server configuration
 * information be supplied. These are referred to as the <em>environment</em>
 * of a context. The <tt>Context</tt> interface provides methods for
 * retrieving and updating this environment.
 *<p>
 * The environment is inherited from the parent context as
 * context methods proceed from one context to the next. Changes to