/*

 * Copyright 1999-2006 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

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

 * the environment of one context do not directly affect those

 * of other contexts.

 *<p>

 * It is implementation-dependent when environment properties are used

 * and/or verified for validity.  For example, some of the

 * security-related properties are used by service providers to "log in"

 * to the directory.  This login process might occur at the time the

 * context is created, or the first time a method is invoked on the

 * context.  When, and whether this occurs at all, is

 * implementation-dependent.  When environment properties are added or

 * removed from the context, verifying the validity of the changes is again

 * implementation-dependent. For example, verification of some properties

 * might occur at the time the change is made, or at the time the next

 * operation is performed on the context, or not at all.

 *<p>

 * Any object with a reference to a context may examine that context's

 * environment.  Sensitive information such as clear-text

 * passwords should not be stored there unless the implementation is

 * known to protect it.

 *

 *<p>

 *<a name=RESOURCEFILES></a>

 *<h4>Resource Files</h4>

 *<p>

 * To simplify the task of setting up the environment

 * required by a JNDI application,

 * application components and service providers may be distributed

 * along with <em>resource files.</em>

 * A JNDI resource file is a file in the properties file format (see

 * {@link java.util.Properties#load <tt>java.util.Properties</tt>}),

 * containing a list of key/value pairs.

 * The key is the name of the property (e.g. "java.naming.factory.object")

 * and the value is a string in the format defined

 * for that property.  Here is an example of a JNDI resource file:

 *

 * <blockquote><tt><pre>

 * 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

 * </pre></tt></blockquote>

 *

 * The JNDI class library reads the resource files and makes the property

 * values freely available.  Thus JNDI resource files should be considered

 * to be "world readable", and sensitive information such as clear-text

 * passwords should not be stored there.

 *<p>

 * There are two kinds of JNDI resource files:

 * <em>provider</em> and <em>application</em>.

 *

 * <h5>Provider Resource Files</h5>

 *

 * Each service provider has an optional resource that lists properties

 * specific to that provider.  The name of this resource is:

 * <blockquote>

 * [<em>prefix</em>/]<tt>jndiprovider.properties</tt>

 * </blockquote>

 * where <em>prefix</em> is

 * the package name of the provider's context implementation(s),

 * with each period (".") converted to a slash ("/").

 *

 * For example, suppose a service provider defines a context

 * implementation with class name <tt>com.sun.jndi.ldap.LdapCtx</tt>.

 * The provider resource for this provider is named

 * <tt>com/sun/jndi/ldap/jndiprovider.properties</tt>.  If the class is

 * not in a package, the resource's name is simply

 * <tt>jndiprovider.properties</tt>.

 *

 * <p>

 * <a name=LISTPROPS></a>

 * Certain methods in the JNDI class library make use of the standard

 * JNDI properties that specify lists of JNDI factories:

 * <ul>

 * <li>java.naming.factory.object

 * <li>java.naming.factory.state

 * <li>java.naming.factory.control

 * <li>java.naming.factory.url.pkgs

 * </ul>

 * The JNDI library will consult the provider resource file

 * when determining the values of these properties.

 * Properties other than these may be set in the provider

 * resource file at the discretion of the service provider.

 * The service provider's documentation should clearly state which

 * properties are allowed; other properties in the file will be ignored.

 *

 * <h5>Application Resource Files</h5>

 *

 * When an application is deployed, it will generally have several

 * codebase directories and JARs in its classpath.  Similarly, when an

 * applet is deployed, it will have a codebase and archives specifying

 * where to find the applet's classes.  JNDI locates (using

 * {@link ClassLoader#getResources <tt>ClassLoader.getResources()</tt>})

 * all <em>application resource files</em> named <tt>jndi.properties</tt>

 * in the classpath.

 * In addition, if the file <i>java.home</i><tt>/lib/jndi.properties</tt>

 * exists and is readable,

 * JNDI treats it as an additional application resource file.

 * (<i>java.home</i> indicates the

 * directory named by the <tt>java.home</tt> system property.)

 * All of the properties contained in these files are placed

 * into the environment of the initial context.  This environment

 * is then inherited by other contexts.

 *

 * <p>

 * For each property found in more than one application resource file,

 * JNDI uses the first value found or, in a few cases where it makes

 * sense to do so, it concatenates all of the values (details are given

 * below).

 * For example, if the "java.naming.factory.object" property is found in

 * three <tt>jndi.properties</tt> resource files, the

 * list of object factories is a concatenation of the property

 * values from all three files.

 * Using this scheme, each deployable component is responsible for

 * listing the factories that it exports.  JNDI automatically

 * collects and uses all of these export lists when searching for factory

 * classes.

 *

 * <h5>Search Algorithm for Properties</h5>

 *

 * When JNDI constructs an initial context, the context's environment

 * is initialized with properties defined in the environment parameter

 * passed to the constructor, the system properties, the applet parameters,

 * and the application resource files.  See

 * <a href=InitialContext.html#ENVIRONMENT><tt>InitialContext</tt></a>

 * for details.

 * This initial environment is then inherited by other context instances.

 *

 * <p>

 * When the JNDI class library needs to determine

 * the value of a property, it does so by merging

 * the values from the following two sources, in order:

 * <ol>

 * <li>The environment of the context being operated on.

 * <li>The provider resource file (<tt>jndiprovider.properties</tt>)

 * for the context being operated on.

 * </ol>

 * For each property found in both of these two sources,

 * JNDI determines the property's value as follows.  If the property is

 * one of the standard JNDI properties that specify a list of JNDI

 * factories (listed <a href=#LISTPROPS>above</a>), the values are

 * concatenated into a single colon-separated list.  For other

 * properties, only the first value found is used.

 *

 * <p>

 * When a service provider needs to determine the value of a property,

 * it will generally take that value directly from the environment.

 * A service provider may define provider-specific properties

 * to be placed in its own provider resource file.  In that

 * case it should merge values as described in the previous paragraph.

 *

 * <p>

 * In this way, each service provider developer can specify a list of

 * factories to use with that service provider. These can be modified by

 * the application resources specified by the deployer of the application

 * or applet, which in turn can be modified by the user.

 *

 * @author Rosanna Lee

 * @author Scott Seligman

 * @author R. Vasudevan

 *

 * @since 1.3

 */

public interface Context {

    /**

     * Retrieves the named object.

     * If <tt>name</tt> is empty, returns a new instance of this context

     * (which represents the same naming context as this context, but its

     * environment may be modified independently and it may be accessed

     * concurrently).

     *

     * @param name

     *          the name of the object to look up

     * @return  the object bound to <tt>name</tt>

     * @throws  NamingException if a naming exception is encountered

     *

     * @see #lookup(String)

     * @see #lookupLink(Name)

     */

    public Object lookup(Name name) throws NamingException;

    /**

     * Retrieves the named object.

     * See {@link #lookup(Name)} for details.

     * @param name

     *          the name of the object to look up

     * @return  the object bound to <tt>name</tt>

     * @throws  NamingException if a naming exception is encountered

     */

    public Object lookup(String name) throws NamingException;

    /**

     * Binds a name to an object.

     * All intermediate contexts and the target context (that named by all

     * but terminal atomic component of the name) must already exist.

     *

     * @param name

     *          the name to bind; may not be empty

     * @param obj

     *          the object to bind; possibly null

     * @throws  NameAlreadyBoundException if name is already bound

     * @throws  javax.naming.directory.InvalidAttributesException

     *          if object did not supply all mandatory attributes

     * @throws  NamingException if a naming exception is encountered

     *

     * @see #bind(String, Object)

     * @see #rebind(Name, Object)

     * @see javax.naming.directory.DirContext#bind(Name, Object,

     *          javax.naming.directory.Attributes)

     */

    public void bind(Name name, Object obj) throws NamingException;

    /**

     * Binds a name to an object.

     * See {@link #bind(Name, Object)} for details.

     *

     * @param name

     *          the name to bind; may not be empty

     * @param obj

     *          the object to bind; possibly null

     * @throws  NameAlreadyBoundException if name is already bound

     * @throws  javax.naming.directory.InvalidAttributesException

     *          if object did not supply all mandatory attributes

     * @throws  NamingException if a naming exception is encountered

     */

    public void bind(String name, Object obj) throws NamingException;

    /**

     * Binds a name to an object, overwriting any existing binding.

     * All intermediate contexts and the target context (that named by all

     * but terminal atomic component of the name) must already exist.

     *

     * <p> If the object is a <tt>DirContext</tt>, any existing attributes

     * associated with the name are replaced with those of the object.

     * Otherwise, any existing attributes associated with the name remain

     * unchanged.

     *

     * @param name

     *          the name to bind; may not be empty

     * @param obj

     *          the object to bind; possibly null

     * @throws  javax.naming.directory.InvalidAttributesException

     *          if object did not supply all mandatory attributes

     * @throws  NamingException if a naming exception is encountered

     *

     * @see #rebind(String, Object)

     * @see #bind(Name, Object)

     * @see javax.naming.directory.DirContext#rebind(Name, Object,

     *          javax.naming.directory.Attributes)

     * @see javax.naming.directory.DirContext

     */

    public void rebind(Name name, Object obj) throws NamingException;

    /**

     * Binds a name to an object, overwriting any existing binding.

     * See {@link #rebind(Name, Object)} for details.

     *

     * @param name

     *          the name to bind; may not be empty

     * @param obj

     *          the object to bind; possibly null

     * @throws  javax.naming.directory.InvalidAttributesException

     *          if object did not supply all mandatory attributes

     * @throws  NamingException if a naming exception is encountered

     */

    public void rebind(String name, Object obj) throws NamingException;

    /**

     * Unbinds the named object.

     * Removes the terminal atomic name in <code>name</code>

     * from the target context--that named by all but the terminal

     * atomic part of <code>name</code>.

     *

     * <p> This method is idempotent.

     * It succeeds even if the terminal atomic name

     * is not bound in the target context, but throws

     * <tt>NameNotFoundException</tt>

     * if any of the intermediate contexts do not exist.

     *

     * <p> Any attributes associated with the name are removed.

     * Intermediate contexts are not changed.

     *

     * @param name

     *          the name to unbind; may not be empty

     * @throws  NameNotFoundException if an intermediate context does not exist

     * @throws  NamingException if a naming exception is encountered

     * @see #unbind(String)

     */

    public void unbind(Name name) throws NamingException;

    /**

     * Unbinds the named object.

     * See {@link #unbind(Name)} for details.

     *

     * @param name

     *          the name to unbind; may not be empty

     * @throws  NameNotFoundException if an intermediate context does not exist

     * @throws  NamingException if a naming exception is encountered

     */

    public void unbind(String name) throws NamingException;

    /**

     * Binds a new name to the object bound to an old name, and unbinds

     * the old name.  Both names are relative to this context.

     * Any attributes associated with the old name become associated

     * with the new name.

     * Intermediate contexts of the old name are not changed.

     *

     * @param oldName

     *          the name of the existing binding; may not be empty

     * @param newName

     *          the name of the new binding; may not be empty

     * @throws  NameAlreadyBoundException if <tt>newName</tt> is already bound

     * @throws  NamingException if a naming exception is encountered

     *

     * @see #rename(String, String)

     * @see #bind(Name, Object)

     * @see #rebind(Name, Object)

     */

    public void rename(Name oldName, Name newName) throws NamingException;

    /**

     * Binds a new name to the object bound to an old name, and unbinds

     * the old name.

     * See {@link #rename(Name, Name)} for details.

     *

     * @param oldName

     *          the name of the existing binding; may not be empty

     * @param newName

     *          the name of the new binding; may not be empty

     * @throws  NameAlreadyBoundException if <tt>newName</tt> is already bound

     * @throws  NamingException if a naming exception is encountered

     */

    public void rename(String oldName, String newName) throws NamingException;

    /**

     * Enumerates the names bound in the named context, along with the

     * class names of objects bound to them.

     * The contents of any subcontexts are not included.

     *

     * <p> If a binding is added to or removed from this context,

     * its effect on an enumeration previously returned is undefined.

     *

     * @param name

     *          the name of the context to list

     * @return  an enumeration of the names and class names of the

     *          bindings in this context.  Each element of the

     *          enumeration is of type <tt>NameClassPair</tt>.

     * @throws  NamingException if a naming exception is encountered

     *

     * @see #list(String)

     * @see #listBindings(Name)

     * @see NameClassPair

     */

    public NamingEnumeration<NameClassPair> list(Name name)

        throws NamingException;

    /**

     * Enumerates the names bound in the named context, along with the

     * class names of objects bound to them.

     * See {@link #list(Name)} for details.

     *

     * @param name

     *          the name of the context to list

     * @return  an enumeration of the names and class names of the

     *          bindings in this context.  Each element of the

     *          enumeration is of type <tt>NameClassPair</tt>.

     * @throws  NamingException if a naming exception is encountered

     */

    public NamingEnumeration<NameClassPair> list(String name)

        throws NamingException;

    /**

     * Enumerates the names bound in the named context, along with the

     * objects bound to them.

     * The contents of any subcontexts are not included.

     *

     * <p> If a binding is added to or removed from this context,

     * its effect on an enumeration previously returned is undefined.

     *

     * @param name

     *          the name of the context to list

     * @return  an enumeration of the bindings in this context.

     *          Each element of the enumeration is of type

     *          <tt>Binding</tt>.

     * @throws  NamingException if a naming exception is encountered

     *

     * @see #listBindings(String)

     * @see #list(Name)

     * @see Binding

      */

    public NamingEnumeration<Binding> listBindings(Name name)

        throws NamingException;

    /**

     * Enumerates the names bound in the named context, along with the

     * objects bound to them.

     * See {@link #listBindings(Name)} for details.

     *

     * @param name

     *          the name of the context to list

     * @return  an enumeration of the bindings in this context.

     *          Each element of the enumeration is of type

     *          <tt>Binding</tt>.

     * @throws  NamingException if a naming exception is encountered

     */

    public NamingEnumeration<Binding> listBindings(String name)

        throws NamingException;

    /**

     * Destroys the named context and removes it from the namespace.