| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| |
| package javax.naming; |
| |
| import java.util.Hashtable; |
| |
| /** |
| * The <code>Context</code> interface describes a naming context comprising a |
| * collection of bindings (see <code>javax.naming.Binding</code>) and methods |
| * for manipulating them. This interface is extended by interfaces |
| * <code>javax.naming.directory.DirContext</code> and |
| * <code>javax.naming.event.EventContext</code>. The class |
| * <code>javax.naming.InitialContext</code> implements the <code>Context</code> |
| * interface. |
| * <p> |
| * Any of the methods may throw a <code>NamingException</code> or one of its |
| * subclasses. The specifications for those exceptions explain the |
| * circumstances in which they may be thrown.</p> |
| * <p> |
| * Name parameters to context methods are each relative to the context. Name |
| * parameters cannot be null. The empty name, whether of type <code>Name</code> |
| * or <code>String</code>, is the name of the initial context. Names may be |
| * composed of multiple components; for example, in the filesystem name |
| * "usr/include/stdio.h", each of the components "usr", "include", "stdio.h" |
| * is an atomic component, but only "stdio.h" is the terminal atomic component. |
| * The example name may be used in context operations providing the intervening |
| * parent contexts for "usr" and "include" already exist. Finally, if the |
| * current context has name "usr/include", then the example name could be the |
| * result of <code>composeName("stdio.h","usr/include")</code>.</p> |
| * <p> |
| * Depending on whether a naming system supports federation, that is, names |
| * that may include components from different naming systems, name parameters |
| * to context methods may be considered differently as described below.</p> |
| * <p> |
| * In systems supporting federation, String name parameters are treated as |
| * composite names. When <code>Name</code> parameters are not instances of |
| * <code>CompositeName</code>, they are deemed to be compound names |
| * (<code>CompoundName</code> instances or subclasses of them). Also, when |
| * using <code>list()</code> or <code>listBindings()</code> to obtain a |
| * <code>NamingEnumeration</code>, all names in the enumeration are string |
| * representations of composite names.</p> |
| * <p> |
| * Where systems do not support federation, a service provider may treat name |
| * parameters to context methods and names found using |
| * <code>NamingEnumeration</code> may either as composite names or as compound |
| * names. See service provider documentation for details.</p> |
| * <p> |
| * Any <code>Name</code> parameter specified to a context method is owned by |
| * the caller and will remain unchanged, but applications should avoid |
| * modifying these <code>Name</code> objects while the operation has not |
| * completed. Any <code>Name</code> object returned by a context operation |
| * becomes owned by the caller.</p> |
| * <p> |
| * JNDI applications can provide preferences and configuration information, |
| * such as security details for authentication to a service, using JNDI |
| * environment properties. JNDI environment properties nearly all begin with |
| * "java.naming." except for provider-specific properties (explained below). |
| * All specified JNDI environment properties together comprise the context |
| * environment and methods are available for examining and manipulating that |
| * environment. The environment of a context may not necessarily contain all |
| * possible JNDI properties; for example, one or more may remain unspecified.</p> |
| * <p> |
| * The set of standard JNDI environment properties is: |
| * <pre> |
| * Property name Value type Notes |
| * ------------- ---------- ----- |
| * java.naming.applet F |
| * java.naming.authoritative F |
| * java.naming.batchsize F |
| * java.naming.dns.url F |
| * java.naming.factory.control C see LdapContext |
| * java.naming.factory.initial F |
| * java.naming.factory.object C |
| * java.naming.factory.state C |
| * java.naming.factory.url.pkgs C |
| * java.naming.language F |
| * java.naming.provider.url F |
| * java.naming.referral F |
| * java.naming.security.authentication F |
| * java.naming.security.credentials F |
| * java.naming.security.principal F |
| * java.naming.security.protocol F |
| * </pre></p> |
| * <p> |
| * For each property above marked with "C" for "concatenate", when encountered |
| * while searching sources of environment properties, values are combined into |
| * a single list separated by colons and becomes the resulting value of that |
| * property.</p> |
| * <p> |
| * For each property above marked with "F" for "first occurrence", when |
| * encountered while searching sources of environment properties, the first |
| * value encountered is the resulting value of that property. In the latter |
| * case, and with additional JNDI environment properties explained further |
| * below, the type and syntax of acceptable property values should be |
| * described in the corresponding documentation for the property. In |
| * particular, a property may accept a value consisting of several pieces of |
| * relevant information, but the search order and precedence for environment |
| * properties ensures that the entire value of the first occurrence of a given |
| * property is deemed the value to be used.</p> |
| * <p> |
| * Additional JNDI environment properties may be defined according to the |
| * needs of the particular service and/or service providers and a few |
| * guidelines should be followed when choosing appropriate names for them. |
| * Such additional properties comprise service-specific, feature-specific, |
| * or provider-specific properties.</p> |
| * <p> |
| * Service-specific JNDI properties may be used by all service providers that |
| * offer implementations for a given service and would include the service |
| * type in the property name prefix. For example, JNDI service providers for |
| * Java RMI should name their service-specific JNDI properties using prefix |
| * "java.naming.rmi.", or LDAP service providers should use prefix |
| * "java.naming.ldap.".</p> |
| * <p> |
| * Feature-specific JNDI properties may be used by all service providers |
| * offering implementations using a particular flavor of a feature and would |
| * include the feature name and the particular flavor name in the property |
| * name prefix. A common example is SASL used by several service providers for |
| * security; appropriate SASL feature-specific properties would use prefix |
| * "java.naming.security.sasl.".</p> |
| * <p> |
| * Provider-specific JNDI properties are used by only a single provider though |
| * a provider may offer more than one service provider implementation. The |
| * provider should ensure uniqueness of their provider properties, for example, |
| * an LDAP service provider from mycom might use a service provider package |
| * name such as "com.mycom.jndi.ldap." as their provider-specific prefix.</p> |
| * <p> |
| * JNDI environment properties can be specified in a <code>Hashtable</code> |
| * and passed as the environment parameter when creating an initial context.</p> |
| * <p> |
| * Two other important sources of JNDI environment properties are resource |
| * files provided by applications and applet parameters (each is considered as |
| * an application resource file) and by service provider implementations |
| * (provider resource files) in the format of Java properties files - see |
| * <code>java.util.Properties</code> class for details.</p> |
| * <p> |
| * At runtime, the application classpath and, where appropriate, the applet |
| * codebase attribute is used to locate the classes to run; when creating the |
| * first initial context, the JNDI also searches the same path for all files |
| * (application resource files) called "jndi.properties"; it is the classpath |
| * associated with the context <code>ClassLoader</code> (for example, the |
| * return value from <code>Thread.getContextClassLoader()</code> or from |
| * <code>ClassLoader.getSystemClassLoader()</code>) which is searched to get |
| * the resource files. Further, a path comprising the value of the "java.home" |
| * system property followed by "lib/jndi.properties" is checked for a readable |
| * file; if one exists, then that file is used as another application resource |
| * file. All application resource files found in the application classpath are |
| * examined, but JNDI properties set in a file found early will override the |
| * same properties also set in a file found later in the classpath.</p> |
| * <p> |
| * Provider resource files are located according to the package prefix for the |
| * service provider's initial context factory and context implementation class |
| * in which dot separator characters are converted into slash path separator |
| * characters to construct a filepath appended with "jndiprovider.properties". |
| * Consider the example where you have a service provider which supplies |
| * a context <code>org.apache.harmony.jndi.example.exampleCtx</code>. |
| * In this case the package prefix is <code>org.apache.harmony.jndi.example</code>. |
| * Substituting slash chars for dots & appending "jndiprovider.properties" |
| * gives you <code>org/apache/harmony/jndi/example/jndiprovider.properties</code>.</p> |
| * <p> |
| * An important part of service provider implementation is to specify certain |
| * standard JNDI properties that are using to locate any of the various |
| * factory classes needed for the implementation; these are: |
| * <pre> |
| * java.naming.factory.control |
| * java.naming.factory.object |
| * java.naming.factory.state |
| * java.naming.factory.url.pkgs - package prefixes used for URL contexts |
| * </pre></p> |
| * <p> |
| * When searching for the above 4 properties only provider resource files |
| * should be examined. Although other properties may be specified in them for |
| * use by the service provider implementation, the JNDI ignores properties |
| * from these files other than those related to factories.</p> |
| * <p> |
| * It should be noted that a provider resource file's properties differ from |
| * those in application resource files in that their values are not |
| * incorporated into the environment. Instead, they are read when the |
| * following methods are invoked with <code>Context</code> and |
| * <code>Hashtable</code> parameters: |
| * <pre> |
| * ControlFactory.getControlInstance - uses java.naming.factory.control |
| * DirectoryManager.getObjectInstance - uses java.naming.factory.object |
| * DirectoryManager.getStateToBind - uses java.naming.factory.state |
| * NamingManager.getObjectInstance - uses java.naming.factory.object |
| * NamingManager.getStateToBind - uses java.naming.factory.state |
| * </pre></p> |
| * <p> |
| * These methods use their <code>Hashtable</code> parameter to get the |
| * environment properties. Then they use the class loader of the |
| * <code>Context</code> parameter to look for the provider resource file. |
| * If the file is found, then the value of the required property is appended |
| * to the value of the required property in the environment. Note that it is |
| * appended for use by this method but the environment itself is unaffected.</p> |
| * <p> |
| * The <code>jndiprovider.properties</code> files may specify additional |
| * properties, but documentation for the service provider should clearly |
| * describe which properties are valid in this file and under what |
| * circumstances.</p> |
| * <p> |
| * To summarize the search order and precedence for JNDI environment |
| * properties, the earliest having highest precedence: |
| * <pre> |
| * 1. environment parameter used to initialize an initial context, |
| * 2. applet parameters, (only used if that environment param does not exist) |
| * 3. system properties, (only used if that environment and applet parameter |
| * do not exist) |
| * 4. application resource files. |
| * </pre></p> |
| * <p> |
| * It should be noted that in the case of applet parameters and system |
| * properties only a subset of the properties are read. These are the |
| * following 7: |
| * <pre> |
| * java.naming.dns.url |
| * java.naming.factory.control |
| * java.naming.factory.initial |
| * java.naming.factory.object |
| * java.naming.factory.state |
| * java.naming.factory.url.pkgs |
| * java.naming.provider.url |
| * </pre></p> |
| * <p> |
| * For a JNDI property found in more than one of those sources, if it is one |
| * of the JNDI factory list properties then values are joined into a |
| * colon-separated list, otherwise the first instance of a property defines |
| * the value to be used.</p> |
| * <p> |
| * The above search order and precedence applies when creating contexts for |
| * any class implementing the <code>Context</code> interface.</p> |
| * <p> |
| * Although a subcontext inherits the environment of its parent context, |
| * subsequent changes to either's environment has no direct effect on the |
| * other. However, applications should avoid dependency on when JNDI properties |
| * are used or verified as this depends on the service provider implementation. |
| * As the environment of a context can be examined by any object that has a |
| * reference to the context, care should be taken to assess the risk to |
| * any security details stored in the environment.</p> |
| * <p> |
| * Multithreaded access to a single <code>Context</code> instance is only safe |
| * when client code uses appropriate synchronization and locking.</p> |
| * <p> |
| * When a <code>NamingEnumeration</code> is returned by a <code>Context</code> |
| * method, the operation should not be considered complete, for concurrency |
| * purposes, if the NamingEnumeration is still being used or if any referrals |
| * are still being followed resulting from that operation.</p> |
| * |
| */ |
| public interface Context { |
| |
| /* |
| * ------------------------------------------------------------------- |
| * Constants |
| * ------------------------------------------------------------------- |
| */ |
| |
| /** |
| * A constant containing environment property name "java.naming.applet". |
| * The property may remain unspecified or may be specified within the |
| * environment parameter used when creating an initial context. When |
| * this environment property is specified, its value must be the currently |
| * executing instance of <code>java.applet.Applet</code> to enable the |
| * operation of initial context creation to search applet parameters first |
| * for other environment properties which may have been specified, before |
| * searching for properties in the constructor environment parameter, |
| * system properties, and application resource files. |
| */ |
| public static final String APPLET = "java.naming.applet"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name |
| * "java.naming.authoritative". An application specifies this property to |
| * indicate whether naming requests must be made to the most authoritative |
| * naming service instance or not. The property may remain unspecified or |
| * may be specified with a string value. If unspecified, the property |
| * value is considered to be "false". A value of "true" means requests |
| * should be made to the most authoritative naming service replicas or |
| * caches that may be available. Any value other than "true" means |
| * requests may be made to any instance of the naming service which need |
| * not be, but may include, the most authoritative. |
| */ |
| public static final String AUTHORITATIVE = "java.naming.authoritative"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name "java.naming.batchsize". |
| * An application specifies this property to indicate a preference to |
| * receive operation results in batches of the given size from the service |
| * provider. The property may remain unspecified or may be specified with |
| * an integer expressed as a string value. If unspecified, the batch size |
| * of operation results is determined by the service provider. The service |
| * provider implementation may use or ignore the specified value. |
| */ |
| public static final String BATCHSIZE = "java.naming.batchsize"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name "java.naming.dns.url". |
| * The property specifies a DNS-scheme URL including the DNS host |
| * including domain names, if any; for example, "dns://9.28.36.7/apache.org". |
| * If the application uses any JNDI URL with DNS names and a search for |
| * this property fails, then the naming operation will throw a |
| * <code>ConfigurationException</code>. |
| */ |
| public static final String DNS_URL = "java.naming.dns.url"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name |
| * "java.naming.factory.initial". The property specifies the name of the |
| * factory class, fully-qualified, that will be used to create an initial |
| * context; for example, "mycom.jndi.testing.spi.DazzleContextFactory". |
| * If the property is not specified, any operation requiring an initial |
| * context will throw a <code>NoInitialContextException</code>. |
| */ |
| public static final String INITIAL_CONTEXT_FACTORY = |
| "java.naming.factory.initial"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name "java.naming.language". |
| * The property indicates the preferred language for operations with the |
| * service provider. The property may remain unspecified or should be a |
| * string comprising a list of language tags according to RFC 1766 |
| * separated by colons. When not specified, the language preference is |
| * selected by the service provider. |
| */ |
| public static final String LANGUAGE = "java.naming.language"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name |
| * "java.naming.factory.object". The property specifies a list of object |
| * factories to be used when the application requests an instance of a |
| * specified object. The value is a string comprising a list of fully |
| * qualified object factory class names separated by colons. |
| */ |
| public static final String OBJECT_FACTORIES = "java.naming.factory.object"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name |
| * "java.naming.provider.url". The property specifies configuration |
| * options for use by the a service provider. The property may remain |
| * unspecified or should be a URL string; for example, |
| * "ldap://ahost.myfirm.com:389". If not specified, the service provider |
| * selects its default configuration. |
| */ |
| public static final String PROVIDER_URL = "java.naming.provider.url"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name "java.naming.referral". |
| * The property specifies how the service provider should process any |
| * referrals encountered during a naming operation. The property may |
| * remain unspecified or specified as one of the following strings: |
| * <ul> |
| * <li>"follow" service provider should always follow referrals</li> |
| * <li>"ignore" service provider should ignore referrals</li> |
| * <li>"throw" service provider should throw ReferralException if it |
| * encounters a referral</li> |
| *</ul> |
| * When not specified, the service provider selects a default value. |
| */ |
| public static final String REFERRAL = "java.naming.referral"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name |
| * "java.naming.security.authentication". The property specifies the |
| * security level to be used in naming operations. The property may remain |
| * unspecified or be one of the strings "none", "simple", "strong". When |
| * not specified, the service provider selects a default value. |
| */ |
| public static final String SECURITY_AUTHENTICATION = |
| "java.naming.security.authentication"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name |
| * "java.naming.security.credentials". The property specifies credentials |
| * of the security principal so that the caller can be authenticated to |
| * the naming service. The property may remain unspecified or be a value |
| * according to the authentication scheme controlling access to the |
| * service. When not specified, the service provider determines how to |
| * respond to service requests affected by the lack of security |
| * credentials. |
| */ |
| public static final String SECURITY_CREDENTIALS = |
| "java.naming.security.credentials"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name |
| * "java.naming.security.principal". The property the name of the security |
| * principal to be used when the caller needs to be authenticated to the |
| * naming service. The property may remain unspecified or be a value |
| * according to the authentication scheme controlling access to the |
| * service. When not specified, the service provider determines how to |
| * respond to service requests affected by the lack of a security |
| * principal. |
| */ |
| public static final String SECURITY_PRINCIPAL = |
| "java.naming.security.principal"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name |
| * "java.naming.security.protocol". The property the name of the security |
| * protocol to be used with the naming service. The property may remain |
| * unspecified or be specified as a string according to the service |
| * provider implementation. When not specified, the service provider |
| * determines how to respond to service requests. |
| */ |
| public static final String SECURITY_PROTOCOL = |
| "java.naming.security.protocol"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name |
| * "java.naming.factory.state". The property specifies a list of state |
| * factories to be used when the application requests the state of a |
| * specified object. The value is a string comprising a list of fully |
| * qualified state factory class names separated by colons. The property |
| * may remain unspecified. |
| */ |
| public static final String STATE_FACTORIES = "java.naming.factory.state"; //$NON-NLS-1$ |
| |
| /** |
| * A constant containing environment property name |
| * "java.naming.factory.url.pkgs". The property specifies a list of |
| * package prefixes that are used to load URL context factories. The value |
| * is a string comprising a list of package prefixes for class names of |
| * URL context factory classes separated by colons. The property may |
| * remain unspecified. In any case, prefix "com.sun.jndi.url" is |
| * automatically added to the list of specified package prefixes or used |
| * as the only package prefix when the property is unspecified. |
| */ |
| public static final String URL_PKG_PREFIXES = |
| "java.naming.factory.url.pkgs"; //$NON-NLS-1$ |
| |
| /* |
| * ------------------------------------------------------------------- |
| * Methods |
| * ------------------------------------------------------------------- |
| */ |
| |
| /** |
| * Adds or replaces the environment property specified by the non-null |
| * string parameter into the environment of this context with the |
| * specified object value. Returns the previous property value if |
| * replaced, or null if the property did not exist in the environment. |
| * |
| * @param s the name of the property to add |
| * @param o the value of the property to add |
| * @return the previous property value if replaced, or null if the |
| * property did not exist in the environment. |
| * @throws NamingException if an error occurs. |
| */ |
| public Object addToEnvironment(String s, Object o) throws NamingException; |
| |
| /** |
| * Binds the specified name to the specified object in this context. The |
| * specified name may not be null. The specified object may be null when |
| * a name bound to a null object is meaningful in the semantics of the |
| * underlying naming system, otherwise a <code>NamingException</code> |
| * is thrown. |
| * |
| * @param n a <code>Name</code>, may not be null |
| * @param o an object to bind with the name, may be null |
| * @throws NamingException if an error occurs. |
| */ |
| public void bind(Name n, Object o) throws NamingException; |
| |
| /** |
| * Binds the specified name to the specified object in this context. The |
| * specified name may not be null. The specified object may be null when |
| * a name bound to a null object is meaningful in the semantics of the |
| * underlying naming system, otherwise a <code>NamingException</code> |
| * is thrown. |
| * |
| * @param s a name in string, may not be null |
| * @param o an object to bind with the name, may be null |
| * @throws NamingException if an error occurs. |
| */ |
| public void bind(String s, Object o) throws NamingException; |
| |
| /** |
| * Closes this context. The result of any further operations on a closed |
| * context is undefined. |
| * |
| * @throws NamingException if an error occurs. |
| */ |
| public void close() throws NamingException; |
| |
| /** |
| * Combines two names into a composite name according to the syntax for |
| * this context. The name <code>pfx</code> is expected to be the name of |
| * one or more of the immediate parent contexts of this context. The name |
| * <code>n</code> is a name relative to this context. Neither |
| * <code>pfx</code> nor <code>n</code> may be null. The combined result |
| * is a name which is relative to the specified parent context names. |
| * |
| * @param n a <code>Name</code>, may not be null |
| * @param pfx a <code>Name</code> serves as perfix, may not be null |
| * @return the combined name |
| * @throws NamingException if an error occurs. |
| */ |
| public Name composeName(Name n, Name pfx) throws NamingException; |
| |
| /** |
| * Combines two names into a composite name according to the syntax for |
| * this context. The name <code>pfx</code> is expected to be the name of |
| * one or more of the immediate parent contexts of this context. The name |
| * <code>s</code> is a name relative to this context. Neither |
| * <code>pfx</code> nor <code>s</code> may be null. The combined result |
| * is a name which is relative to the specified parent context names. |
| * |
| * @param s a name in string, may not be null |
| * @param pfx a name in string, serves as prefix, may not be null |
| * @return the combined name in string |
| * @throws NamingException if an error occurs. |
| */ |
| public String composeName(String s, String pfx) throws NamingException; |
| |
| /** |
| * Creates a new context with the specified name as a child of this |
| * context and creates a binding for the name with the new context |
| * object in this context. This is analogous to creating a new lower |
| * level in a hierarchical naming system. |
| * |
| * @param n the name of the new subcontext |
| * @return the created subcontext |
| * @throws NamingException if an error occurs. |
| */ |
| public Context createSubcontext(Name n) throws NamingException; |
| |
| /** |
| * Creates a new context with the specified name as a child of this |
| * context and creates a binding for the name with the new context |
| * object in this context. This is analogous to creating a new lower |
| * level in a hierarchical naming system. |
| * |
| * @param s the name of the new subcontext, in string |
| * @return the created subcontext |
| * @throws NamingException if an error occurs. |
| */ |
| public Context createSubcontext(String s) throws NamingException; |
| |
| /** |
| * Removes a child context with the specified name from this context |
| * together with any attributes associated with that name. If the |
| * specified context does not exist, but intervening contexts do exist, |
| * then the operation is is considered to succeed. |
| * <p> |
| * Care must be taken with composite names crossing multiple naming |
| * systems. A composite name containing a name component which is bound |
| * to an object in a different naming system cannot be used to destroy |
| * that name subcontext because the subcontext is not of the same type |
| * as the context containing the binding. <code>Unbind()</code> can be |
| * used to destroy the binding of the specified name in this context to |
| * the object in the other naming system. To remove the context object |
| * in the other naming system, first obtain a context belonging to the |
| * other naming system, then use <code>destroySubcontext()</code> on that |
| * context.</p> |
| * |
| * @param n the name of the subcontext to destroy |
| * @throws NamingException if an error occurs. |
| */ |
| public void destroySubcontext(Name n) throws NamingException; |
| |
| /** |
| * Removes a child context with the specified name from this context |
| * together with any attributes associated with that name. If the |
| * specified context does not exist, but intervening contexts do exist, |
| * then the operation is considered to succeed. |
| * <p> |
| * Care must be taken with composite names crossing multiple naming |
| * systems. A composite name containing a name component which is bound |
| * to an object in a different naming system cannot be used to destroy |
| * that name subcontext because the subcontext is not of the same type |
| * as the context containing the binding. <code>Unbind()</code> can be |
| * used to destroy the binding of the specified name in this context to |
| * the object in the other naming system. To remove the context object |
| * in the other naming system, first obtain a context belonging to the |
| * other naming system, then use <code>destroySubcontext()</code> on that |
| * context.</p> |
| * |
| * @param s the name of the subcontext to destroy |
| * @throws NamingException if an error occurs. |
| */ |
| public void destroySubcontext(String s) throws NamingException; |
| |
| /** |
| * Returns a non-null reference to the current environment properties for |
| * this context. The only proper ways to modify the properties for this |
| * context are using the <code>addToEnvironment()</code> and |
| * <code>removeFromEnvironment()</code> methods. |
| * |
| * @return a non-null reference to the current environment properties for |
| * this context, which should not be modified |
| * @throws NamingException if an error occurs. |
| */ |
| public Hashtable<?, ?> getEnvironment() throws NamingException; |
| |
| /** |
| * Returns the complete name as a string for this context in the |
| * namespace. For example, in a namespace accessed using a file system |
| * service provider on a computer running the Windows operating system, |
| * <code>getNameInNamespace()</code> will return a string comprising the |
| * current working disk drive such as "F:\". The returned name is never |
| * null and should not be used in any naming operations. |
| * |
| * @return the complete name as a string for this context in the |
| * namespace |
| * @throws NamingException if an error occurs. |
| * @throws OperationNotSupportedException in cases of naming systems |
| * where a full name has no meaning. |
| */ |
| public String getNameInNamespace() throws NamingException; |
| |
| /** |
| * Returns a parser object for the named context. When using a federation |
| * of naming systems in which each has its own rules for parsing names for |
| * its namespace, each naming system will have a different parser. The |
| * parser for a given context can parse a name composed of several |
| * components into atomic components according to the rules for the naming |
| * system associated with the specified context. |
| * |
| * @param n a <code>Name</code> |
| * @return a parser object for the named context |
| * @throws NamingException if an error occurs. |
| */ |
| public NameParser getNameParser(Name n) throws NamingException; |
| |
| /** |
| * Returns a parser object for the named context. When using a federation |
| * of naming systems in which each has its own rules for parsing names for |
| * its namespace, each naming system will have a different parser. The |
| * parser for a given context can parse a name composed of several |
| * components into atomic components according to the rules for the naming |
| * system associated with the specified context. |
| * |
| * @param s a name in string |
| * @return a parser object for the named context |
| * @throws NamingException if an error occurs. |
| */ |
| public NameParser getNameParser(String s) throws NamingException; |
| |
| /** |
| * Returns an enumeration of the bindings of the context for the specified |
| * name excluding any bindings for any subcontexts. If any binding for the |
| * context is changed before closing the enumeration, the state of the |
| * enumeration is undefined. Each element of the enumeration is a |
| * <code>NameClassPair</code> object. |
| * |
| * @param n a <code>Name</code> |
| * @return an enumeration of the bindings of the context for the |
| * specified name excluding any bindings for any subcontexts |
| * @throws NamingException if an error occurs. |
| */ |
| public NamingEnumeration<NameClassPair> list(Name n) |
| throws NamingException; |
| |
| /** |
| * Returns an enumeration of the bindings of the context for the specified |
| * name excluding any bindings for any subcontexts. If any binding for the |
| * context is changed before closing the enumeration, the state of the |
| * enumeration is undefined. Each element of the enumeration is a |
| * <code>NameClassPair</code> object. |
| * |
| * @param s a name in string |
| * @return an enumeration of the bindings of the context for the |
| * specified name excluding any bindings for any subcontexts |
| * @throws NamingException if an error occurs. |
| */ |
| public NamingEnumeration<NameClassPair> list(String s) |
| throws NamingException; |
| |
| /** |
| * Returns an enumeration of the bindings of the context for the specified |
| * name excluding any bindings for any subcontexts. If any binding for the |
| * context is changed before closing the enumeration, the state of the |
| * enumeration is undefined. Each element of the enumeration is a |
| * <code>Binding</code> object. |
| * |
| * @param n a <code>Name</code> |
| * @return an enumeration of the bindings of the context for the specified |
| * name excluding any bindings for any subcontexts |
| * @throws NamingException if an error occurs. |
| */ |
| public NamingEnumeration<Binding> listBindings(Name n) |
| throws NamingException; |
| |
| /** |
| * Returns an enumeration of the bindings of the context for the specified |
| * name excluding any bindings for any subcontexts. If any binding for the |
| * context is changed before closing the enumeration, the state of the |
| * enumeration is undefined. Each element of the enumeration is a |
| * <code>Binding</code> object. |
| * |
| * @param s a name in string |
| * @return an enumeration of the bindings of the context for the specified |
| * name excluding any bindings for any subcontexts |
| * @throws NamingException if an error occurs. |
| */ |
| public NamingEnumeration<Binding> listBindings(String s) throws NamingException; |
| |
| /** |
| * Returns the object bound to the specified name in this context. If the |
| * specified name is empty, a new instance of this context is returned, |
| * complete with its own environment properties. |
| * |
| * @param n a <code>Name</code> to lookup |
| * @return the object bound to the specified name in this context |
| * @throws NamingException if an error occurs. |
| */ |
| public Object lookup(Name n) throws NamingException; |
| |
| /** |
| * Returns the object bound to the specified name in this context. If the |
| * specified name is empty, a new instance of this context is returned, |
| * complete with its own environment properties. |
| * |
| * @param s a name to lookup |
| * @return the object bound to the specified name in this context |
| * @throws NamingException if an error occurs. |
| */ |
| public Object lookup(String s) throws NamingException; |
| |
| /** |
| * Returns the object bound to the specified name in this context by |
| * following any links. If the specified name is not a link, then the |
| * object is returned. |
| * |
| * @param n a <code>Name</code> to lookup |
| * @return the object bound to the specified name in this context by |
| * following any links |
| * @throws NamingException if an error occurs. |
| */ |
| public Object lookupLink(Name n) throws NamingException; |
| |
| /** |
| * Returns the object bound to the specified name in this context by |
| * following any links. If the specified name is not a link, then the |
| * object is returned. |
| * |
| * @param s a name in string to lookup |
| * @return the object bound to the specified name in this context by |
| * following any links |
| * @throws NamingException if an error occurs. |
| */ |
| public Object lookupLink(String s) throws NamingException; |
| |
| /** |
| * Binds the specified name to the specified object, replacing any |
| * existing binding for the specified name. The specified name may |
| * not be empty. The specified object may be null. |
| * |
| * @param n a <code>Name</code> to rebind, may not be null |
| * @param o an object to bind with the name, may be null |
| * @throws NamingException if an error occurs. |
| */ |
| public void rebind(Name n, Object o) throws NamingException; |
| |
| /** |
| * Binds the specified name to the specified object, replacing any |
| * existing binding for the specified name. The specified name may |
| * not be empty. The specified object may be null. |
| * |
| * @param s a name in string to rebind, may not be null |
| * @param o an object tobind with the name, may be null |
| * @throws NamingException if an error occurs. |
| */ |
| public void rebind(String s, Object o) throws NamingException; |
| |
| /** |
| * Removes the environment property specified by the non-null parameter |
| * from the environment of this context. Returns the value that the |
| * property had before removal, or null if the property did not exist |
| * in the environment. |
| * |
| * @param s a property name |
| * @return the value that the property had before removal, or null if the |
| * property did not exist in the environment |
| * @throws NamingException if an error occurs. |
| */ |
| public Object removeFromEnvironment(String s) throws NamingException; |
| |
| /** |
| * Binds a specified new name to the object, and any attributes, |
| * previously bound to the specified old name. The old name is removed |
| * from the bindings for this context. |
| * |
| * @param nOld the old name |
| * @param nNew the new name |
| * @throws NameAlreadyBoundException if the new is already bound |
| * @throws NamingException if an error occurs. |
| */ |
| public void rename(Name nOld, Name nNew) throws NamingException; |
| |
| /** |
| * Binds a specified new name to the object, and any attributes, |
| * previously bound to the specified old name. The old name is removed |
| * from the bindings for this context. Neither the new nor the old name |
| * may be empty. |
| * |
| * @param sOld the old name in string |
| * @param sNew the new name in string |
| * @throws NameAlreadyBoundException if the new is already bound |
| * @throws NamingException if an error occurs. |
| */ |
| public void rename(String sOld, String sNew) throws NamingException; |
| |
| /** |
| * Removes the terminal atomic name component of the specified name from |
| * the bindings in this context, together with any attributes associated |
| * with the terminal atomic name. Providing that other parts of the |
| * specified name exist in this context's bindings, the operation succeeds |
| * whether or not the terminal atomic name exists, otherwise a |
| * <code>NameNotFoundException</code> is thrown. |
| * Any intermediate contexts remain unchanged. |
| * |
| * @param n a <code>Name</code> to unbind |
| * @throws NamingException if an error occurs. |
| */ |
| public void unbind(Name n) throws NamingException; |
| |
| /** |
| * Removes the terminal atomic name component of the specified name from |
| * the bindings in this context, together with any attributes associated |
| * with the terminal atomic name. Providing that other parts of the |
| * specified name exist in this context's bindings, the operation succeeds |
| * whether or not the terminal atomic name exists, otherwise a |
| * <code>NameNotFoundException</code> is thrown. |
| * Any intermediate contexts remain unchanged. |
| * |
| * @param s a name in string to unbind |
| * @throws NamingException if an error occurs. |
| */ |
| public void unbind(String s) throws NamingException; |
| |
| } |
| |
| |
