| /* |
| * Copyright (c) 1999, 2006, Oracle and/or its affiliates. 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. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.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"; |
| }; |
