--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/javax/naming/Context.java Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,1099 @@
+/*
+ * 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.
+ * Any attributes associated with the name are also removed.
+ * Intermediate contexts are not destroyed.
+ *
+ * <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> In a federated naming system, a context from one naming system
+ * may be bound to a name in another. One can subsequently
+ * look up and perform operations on the foreign context using a
+ * composite name. However, an attempt destroy the context using
+ * this composite name will fail with
+ * <tt>NotContextException</tt>, because the foreign context is not
+ * a "subcontext" of the context in which it is bound.
+ * Instead, use <tt>unbind()</tt> to remove the
+ * binding of the foreign context. Destroying the foreign context
+ * requires that the <tt>destroySubcontext()</tt> be performed
+ * on a context from the foreign context's "native" naming system.
+ *
+ * @param name
+ * the name of the context to be destroyed; may not be empty
+ * @throws NameNotFoundException if an intermediate context does not exist
+ * @throws NotContextException if the name is bound but does not name a
+ * context, or does not name a context of the appropriate type
+ * @throws ContextNotEmptyException if the named context is not empty
+ * @throws NamingException if a naming exception is encountered
+ *
+ * @see #destroySubcontext(String)
+ */
+ public void destroySubcontext(Name name) throws NamingException;
+
+ /**
+ * Destroys the named context and removes it from the namespace.
+ * See {@link #destroySubcontext(Name)} for details.
+ *
+ * @param name
+ * the name of the context to be destroyed; may not be empty
+ * @throws NameNotFoundException if an intermediate context does not exist
+ * @throws NotContextException if the name is bound but does not name a
+ * context, or does not name a context of the appropriate type
+ * @throws ContextNotEmptyException if the named context is not empty
+ * @throws NamingException if a naming exception is encountered
+ */
+ public void destroySubcontext(String name) throws NamingException;
+
+ /**
+ * Creates and binds a new context.
+ * Creates a new context with the given name and binds it in
+ * the target context (that named by all but terminal atomic
+ * component of the name). All intermediate contexts and the
+ * target context must already exist.
+ *
+ * @param name
+ * the name of the context to create; may not be empty
+ * @return the newly created context
+ *
+ * @throws NameAlreadyBoundException if name is already bound
+ * @throws javax.naming.directory.InvalidAttributesException
+ * if creation of the subcontext requires specification of
+ * mandatory attributes
+ * @throws NamingException if a naming exception is encountered
+ *
+ * @see #createSubcontext(String)
+ * @see javax.naming.directory.DirContext#createSubcontext
+ */
+ public Context createSubcontext(Name name) throws NamingException;
+
+ /**
+ * Creates and binds a new context.
+ * See {@link #createSubcontext(Name)} for details.
+ *
+ * @param name
+ * the name of the context to create; may not be empty
+ * @return the newly created context
+ *
+ * @throws NameAlreadyBoundException if name is already bound
+ * @throws javax.naming.directory.InvalidAttributesException
+ * if creation of the subcontext requires specification of
+ * mandatory attributes
+ * @throws NamingException if a naming exception is encountered
+ */
+ public Context createSubcontext(String name) throws NamingException;
+
+ /**
+ * Retrieves the named object, following links except
+ * for the terminal atomic component of the name.
+ * If the object bound to <tt>name</tt> is not a link,
+ * returns the object itself.
+ *
+ * @param name
+ * the name of the object to look up
+ * @return the object bound to <tt>name</tt>, not following the
+ * terminal link (if any).
+ * @throws NamingException if a naming exception is encountered
+ *
+ * @see #lookupLink(String)
+ */
+ public Object lookupLink(Name name) throws NamingException;
+
+ /**
+ * Retrieves the named object, following links except
+ * for the terminal atomic component of the name.
+ * See {@link #lookupLink(Name)} for details.
+ *
+ * @param name
+ * the name of the object to look up
+ * @return the object bound to <tt>name</tt>, not following the
+ * terminal link (if any)
+ * @throws NamingException if a naming exception is encountered
+ */
+ public Object lookupLink(String name) throws NamingException;
+
+ /**
+ * Retrieves the parser associated with the named context.
+ * In a federation of namespaces, different naming systems will
+ * parse names differently. This method allows an application
+ * to get a parser for parsing names into their atomic components
+ * using the naming convention of a particular naming system.
+ * Within any single naming system, <tt>NameParser</tt> objects
+ * returned by this method must be equal (using the <tt>equals()</tt>
+ * test).
+ *
+ * @param name
+ * the name of the context from which to get the parser
+ * @return a name parser that can parse compound names into their atomic
+ * components
+ * @throws NamingException if a naming exception is encountered
+ *
+ * @see #getNameParser(String)
+ * @see CompoundName
+ */
+ public NameParser getNameParser(Name name) throws NamingException;
+
+ /**
+ * Retrieves the parser associated with the named context.
+ * See {@link #getNameParser(Name)} for details.
+ *
+ * @param name
+ * the name of the context from which to get the parser
+ * @return a name parser that can parse compound names into their atomic
+ * components
+ * @throws NamingException if a naming exception is encountered
+ */
+ public NameParser getNameParser(String name) throws NamingException;
+
+ /**
+ * Composes the name of this context with a name relative to
+ * this context.
+ * Given a name (<code>name</code>) relative to this context, and
+ * the name (<code>prefix</code>) of this context relative to one
+ * of its ancestors, this method returns the composition of the
+ * two names using the syntax appropriate for the naming
+ * system(s) involved. That is, if <code>name</code> names an
+ * object relative to this context, the result is the name of the
+ * same object, but relative to the ancestor context. None of the
+ * names may be null.
+ * <p>
+ * For example, if this context is named "wiz.com" relative
+ * to the initial context, then
+ * <pre>
+ * composeName("east", "wiz.com") </pre>
+ * might return <code>"east.wiz.com"</code>.
+ * If instead this context is named "org/research", then
+ * <pre>
+ * composeName("user/jane", "org/research") </pre>
+ * might return <code>"org/research/user/jane"</code> while
+ * <pre>
+ * composeName("user/jane", "research") </pre>
+ * returns <code>"research/user/jane"</code>.
+ *
+ * @param name
+ * a name relative to this context
+ * @param prefix
+ * the name of this context relative to one of its ancestors
+ * @return the composition of <code>prefix</code> and <code>name</code>
+ * @throws NamingException if a naming exception is encountered
+ *
+ * @see #composeName(String, String)
+ */
+ public Name composeName(Name name, Name prefix)
+ throws NamingException;
+
+ /**
+ * Composes the name of this context with a name relative to
+ * this context.
+ * See {@link #composeName(Name, Name)} for details.
+ *
+ * @param name
+ * a name relative to this context
+ * @param prefix
+ * the name of this context relative to one of its ancestors
+ * @return the composition of <code>prefix</code> and <code>name</code>
+ * @throws NamingException if a naming exception is encountered
+ */
+ public String composeName(String name, String prefix)
+ throws NamingException;
+
+ /**
+ * Adds a new environment property to the environment of this
+ * context. If the property already exists, its value is overwritten.
+ * See class description for more details on environment properties.
+ *
+ * @param propName
+ * the name of the environment property to add; may not be null
+ * @param propVal
+ * the value of the property to add; may not be null
+ * @return the previous value of the property, or null if the property was
+ * not in the environment before
+ * @throws NamingException if a naming exception is encountered
+ *
+ * @see #getEnvironment()
+ * @see #removeFromEnvironment(String)
+ */
+ public Object addToEnvironment(String propName, Object propVal)
+ throws NamingException;
+
+ /**
+ * Removes an environment property from the environment of this
+ * context. See class description for more details on environment
+ * properties.
+ *
+ * @param propName
+ * the name of the environment property to remove; may not be null
+ * @return the previous value of the property, or null if the property was
+ * not in the environment
+ * @throws NamingException if a naming exception is encountered
+ *
+ * @see #getEnvironment()
+ * @see #addToEnvironment(String, Object)
+ */
+ public Object removeFromEnvironment(String propName)
+ throws NamingException;
+
+ /**
+ * Retrieves the environment in effect for this context.
+ * See class description for more details on environment properties.
+ *
+ * <p> The caller should not make any changes to the object returned:
+ * their effect on the context is undefined.
+ * The environment of this context may be changed using
+ * <tt>addToEnvironment()</tt> and <tt>removeFromEnvironment()</tt>.
+ *
+ * @return the environment of this context; never null
+ * @throws NamingException if a naming exception is encountered
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ */
+ public Hashtable<?,?> getEnvironment() throws NamingException;
+
+ /**
+ * Closes this context.
+ * This method releases this context's resources immediately, instead of
+ * waiting for them to be released automatically by the garbage collector.
+ *
+ * <p> This method is idempotent: invoking it on a context that has
+ * already been closed has no effect. Invoking any other method
+ * on a closed context is not allowed, and results in undefined behaviour.
+ *
+ * @throws NamingException if a naming exception is encountered
+ */
+ public void close() throws NamingException;
+
+ /**
+ * Retrieves the full name of this context within its own namespace.
+ *
+ * <p> Many naming services have a notion of a "full name" for objects
+ * in their respective namespaces. For example, an LDAP entry has
+ * a distinguished name, and a DNS record has a fully qualified name.
+ * This method allows the client application to retrieve this name.
+ * The string returned by this method is not a JNDI composite name
+ * and should not be passed directly to context methods.
+ * In naming systems for which the notion of full name does not
+ * make sense, <tt>OperationNotSupportedException</tt> is thrown.
+ *
+ * @return this context's name in its own namespace; never null
+ * @throws OperationNotSupportedException if the naming system does
+ * not have the notion of a full name
+ * @throws NamingException if a naming exception is encountered
+ *
+ * @since 1.3
+ */
+ public String getNameInNamespace() throws NamingException;
+
+// public static final: JLS says recommended style is to omit these modifiers
+// because they are the default
+
+ /**
+ * Constant that holds the name of the environment property
+ * for specifying the initial context factory to use. The value
+ * of the property should be the fully qualified class name
+ * of the factory class that will create an initial context.
+ * This property may be specified in the environment parameter
+ * passed to the initial context constructor, an applet parameter,
+ * a system property, or an application resource file.
+ * If it is not specified in any of these sources,
+ * <tt>NoInitialContextException</tt> is thrown when an initial
+ * context is required to complete an operation.
+ *
+ * <p> The value of this constant is "java.naming.factory.initial".
+ *
+ * @see InitialContext
+ * @see javax.naming.directory.InitialDirContext
+ * @see javax.naming.spi.NamingManager#getInitialContext
+ * @see javax.naming.spi.InitialContextFactory
+ * @see NoInitialContextException
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ * @see #APPLET
+ */
+ String INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial";
+
+ /**
+ * Constant that holds the name of the environment property
+ * for specifying the list of object factories to use. The value
+ * of the property should be a colon-separated list of the fully
+ * qualified class names of factory classes that will create an object
+ * given information about the object.
+ * This property may be specified in the environment, an applet
+ * parameter, a system property, or one or more resource files.
+ *
+ * <p> The value of this constant is "java.naming.factory.object".
+ *
+ * @see javax.naming.spi.NamingManager#getObjectInstance
+ * @see javax.naming.spi.ObjectFactory
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ * @see #APPLET
+ */
+ String OBJECT_FACTORIES = "java.naming.factory.object";
+
+ /**
+ * Constant that holds the name of the environment property
+ * for specifying the list of state factories to use. The value
+ * of the property should be a colon-separated list of the fully
+ * qualified class names of state factory classes that will be used
+ * to get an object's state given the object itself.
+ * This property may be specified in the environment, an applet
+ * parameter, a system property, or one or more resource files.
+ *
+ * <p> The value of this constant is "java.naming.factory.state".
+ *
+ * @see javax.naming.spi.NamingManager#getStateToBind
+ * @see javax.naming.spi.StateFactory
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ * @see #APPLET
+ * @since 1.3
+ */
+ String STATE_FACTORIES = "java.naming.factory.state";
+
+ /**
+ * Constant that holds the name of the environment property
+ * for specifying the list of package prefixes to use when
+ * loading in URL context factories. The value
+ * of the property should be a colon-separated list of package
+ * prefixes for the class name of the factory class that will create
+ * a URL context factory.
+ * This property may be specified in the environment,
+ * an applet parameter, a system property, or one or more
+ * resource files.
+ * The prefix <tt>com.sun.jndi.url</tt> is always appended to
+ * the possibly empty list of package prefixes.
+ *
+ * <p> The value of this constant is "java.naming.factory.url.pkgs".
+ *
+ * @see javax.naming.spi.NamingManager#getObjectInstance
+ * @see javax.naming.spi.NamingManager#getURLContext
+ * @see javax.naming.spi.ObjectFactory
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ * @see #APPLET
+ */
+ String URL_PKG_PREFIXES = "java.naming.factory.url.pkgs";
+
+ /**
+ * Constant that holds the name of the environment property
+ * for specifying configuration information for the service provider
+ * to use. The value of the property should contain a URL string
+ * (e.g. "ldap://somehost:389").
+ * This property may be specified in the environment,
+ * an applet parameter, a system property, or a resource file.
+ * If it is not specified in any of these sources,
+ * the default configuration is determined by the service provider.
+ *
+ * <p> The value of this constant is "java.naming.provider.url".
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ * @see #APPLET
+ */
+ String PROVIDER_URL = "java.naming.provider.url";
+
+ /**
+ * Constant that holds the name of the environment property
+ * for specifying the DNS host and domain names to use for the
+ * JNDI URL context (for example, "dns://somehost/wiz.com").
+ * This property may be specified in the environment,
+ * an applet parameter, a system property, or a resource file.
+ * If it is not specified in any of these sources
+ * and the program attempts to use a JNDI URL containing a DNS name,
+ * a <tt>ConfigurationException</tt> will be thrown.
+ *
+ * <p> The value of this constant is "java.naming.dns.url".
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ */
+ String DNS_URL = "java.naming.dns.url";
+
+ /**
+ * Constant that holds the name of the environment property for
+ * specifying the authoritativeness of the service requested.
+ * If the value of the property is the string "true", it means
+ * that the access is to the most authoritative source (i.e. bypass
+ * any cache or replicas). If the value is anything else,
+ * the source need not be (but may be) authoritative.
+ * If unspecified, the value defaults to "false".
+ *
+ * <p> The value of this constant is "java.naming.authoritative".
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ */
+ String AUTHORITATIVE = "java.naming.authoritative";
+
+ /**
+ * Constant that holds the name of the environment property for
+ * specifying the batch size to use when returning data via the
+ * service's protocol. This is a hint to the provider to return
+ * the results of operations in batches of the specified size, so
+ * the provider can optimize its performance and usage of resources.
+ * The value of the property is the string representation of an
+ * integer.
+ * If unspecified, the batch size is determined by the service
+ * provider.
+ *
+ * <p> The value of this constant is "java.naming.batchsize".
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ */
+ String BATCHSIZE = "java.naming.batchsize";
+
+ /**
+ * Constant that holds the name of the environment property for
+ * specifying how referrals encountered by the service provider
+ * are to be processed. The value of the property is one of the
+ * following strings:
+ * <dl>
+ * <dt>"follow"
+ * <dd>follow referrals automatically
+ * <dt>"ignore"
+ * <dd>ignore referrals
+ * <dt>"throw"
+ * <dd>throw <tt>ReferralException</tt> when a referral is encountered.
+ * </dl>
+ * If this property is not specified, the default is
+ * determined by the provider.
+ *
+ * <p> The value of this constant is "java.naming.referral".
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ */
+ String REFERRAL = "java.naming.referral";
+
+ /**
+ * Constant that holds the name of the environment property for
+ * specifying the security protocol to use.
+ * Its value is a string determined by the service provider
+ * (e.g. "ssl").
+ * If this property is unspecified,
+ * the behaviour is determined by the service provider.
+ *
+ * <p> The value of this constant is "java.naming.security.protocol".
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ */
+ String SECURITY_PROTOCOL = "java.naming.security.protocol";
+
+ /**
+ * Constant that holds the name of the environment property for
+ * specifying the security level to use.
+ * Its value is one of the following strings:
+ * "none", "simple", "strong".
+ * If this property is unspecified,
+ * the behaviour is determined by the service provider.
+ *
+ * <p> The value of this constant is "java.naming.security.authentication".
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ */
+ String SECURITY_AUTHENTICATION = "java.naming.security.authentication";
+
+ /**
+ * Constant that holds the name of the environment property for
+ * specifying the identity of the principal for authenticating
+ * the caller to the service. The format of the principal
+ * depends on the authentication scheme.
+ * If this property is unspecified,
+ * the behaviour is determined by the service provider.
+ *
+ * <p> The value of this constant is "java.naming.security.principal".
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ */
+ String SECURITY_PRINCIPAL = "java.naming.security.principal";
+
+ /**
+ * Constant that holds the name of the environment property for
+ * specifying the credentials of the principal for authenticating
+ * the caller to the service. The value of the property depends
+ * on the authentication scheme. For example, it could be a hashed
+ * password, clear-text password, key, certificate, and so on.
+ * If this property is unspecified,
+ * the behaviour is determined by the service provider.
+ *
+ * <p> The value of this constant is "java.naming.security.credentials".
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ */
+
+ String SECURITY_CREDENTIALS = "java.naming.security.credentials";
+ /**
+ * Constant that holds the name of the environment property for
+ * specifying the preferred language to use with the service.
+ * The value of the property is a colon-separated list of language
+ * tags as defined in RFC 1766.
+ * If this property is unspecified,
+ * the language preference is determined by the service provider.
+ *
+ * <p> The value of this constant is "java.naming.language".
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ */
+ String LANGUAGE = "java.naming.language";
+
+ /**
+ * Constant that holds the name of the environment property for
+ * specifying an applet for the initial context constructor to use
+ * when searching for other properties.
+ * The value of this property is the
+ * <tt>java.applet.Applet</tt> instance that is being executed.
+ * This property may be specified in the environment parameter
+ * passed to the initial context constructor.
+ * When this property is set, each property that the initial context
+ * constructor looks for in the system properties is first looked for
+ * in the applet's parameter list.
+ * If this property is unspecified, the initial context constructor
+ * will search for properties only in the environment parameter
+ * passed to it, the system properties, and application resource files.
+ *
+ * <p> The value of this constant is "java.naming.applet".
+ *
+ * @see #addToEnvironment(String, Object)
+ * @see #removeFromEnvironment(String)
+ * @see InitialContext
+ *
+ * @since 1.3
+ */
+ String APPLET = "java.naming.applet";
+};