1 /*
   2  * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.naming;
  27 
  28 import java.util.Hashtable;
  29 
  30 /**
  31  * This interface represents a naming context, which
  32  * consists of a set of name-to-object bindings.
  33  * It contains methods for examining and updating these bindings.
  34  *
  35  * <h1>Names</h1>
  36  * Each name passed as an argument to a <tt>Context</tt> method is relative
  37  * to that context.  The empty name is used to name the context itself.
  38  * A name parameter may never be null.
  39  * <p>
  40  * Most of the methods have overloaded versions with one taking a
  41  * <code>Name</code> parameter and one taking a <code>String</code>.
  42  * These overloaded versions are equivalent in that if
  43  * the <code>Name</code> and <code>String</code> parameters are just
  44  * different representations of the same name, then the overloaded
  45  * versions of the same methods behave the same.
  46  * In the method descriptions below, only one version is fully documented.
  47  * The second version instead has a link to the first:  the same
  48  * documentation applies to both.
  49  * <p>
  50  * For systems that support federation, <tt>String</tt> name arguments to
  51  * <tt>Context</tt> methods are composite names. Name arguments that are
  52  * instances of <tt>CompositeName</tt> are treated as composite names,
  53  * while <tt>Name</tt> arguments that are not instances of
  54  * <tt>CompositeName</tt> are treated as compound names (which might be
  55  * instances of <tt>CompoundName</tt> or other implementations of compound
  56  * names). This allows the results of <tt>NameParser.parse()</tt> to be used as
  57  * arguments to the <tt>Context</tt> methods.
  58  * Prior to JNDI 1.2, all name arguments were treated as composite names.
  59  *<p>
  60  * Furthermore, for systems that support federation, all names returned
  61  * in a <tt>NamingEnumeration</tt>
  62  * from <tt>list()</tt> and <tt>listBindings()</tt> are composite names
  63  * represented as strings.
  64  * See <tt>CompositeName</tt> for the string syntax of names.
  65  *<p>
  66  * For systems that do not support federation, the name arguments (in
  67  * either <tt>Name</tt> or <tt>String</tt> forms) and the names returned in
  68  * <tt>NamingEnumeration</tt> may be names in their own namespace rather than
  69  * names in a composite namespace, at the discretion of the service
  70  * provider.
  71  *
  72  *<h1>Exceptions</h1>
  73  * All the methods in this interface can throw a <tt>NamingException</tt> or
  74  * any of its subclasses. See <tt>NamingException</tt> and their subclasses
  75  * for details on each exception.
  76  *
  77  *<h1>Concurrent Access</h1>
  78  * A Context instance is not guaranteed to be synchronized against
  79  * concurrent access by multiple threads.  Threads that need to access
  80  * a single Context instance concurrently should synchronize amongst
  81  * themselves and provide the necessary locking.  Multiple threads
  82  * each manipulating a different Context instance need not
  83  * synchronize.  Note that the {@link #lookup(Name) <tt>lookup</tt>}
  84  * method, when passed an empty name, will return a new Context instance
  85  * representing the same naming context.
  86  *<p>
  87  * For purposes of concurrency control,
  88  * a Context operation that returns a <tt>NamingEnumeration</tt> is
  89  * not considered to have completed while the enumeration is still in
  90  * use, or while any referrals generated by that operation are still
  91  * being followed.
  92  *
  93  *
  94  *<h1>Parameters</h1>
  95  * A <tt>Name</tt> parameter passed to any method of the
  96  * <tt>Context</tt> interface or one of its subinterfaces
  97  * will not be modified by the service provider.
  98  * The service provider may keep a reference to it
  99  * for the duration of the operation, including any enumeration of the
 100  * method's results and the processing of any referrals generated.
 101  * The caller should not modify the object during this time.
 102  * A <tt>Name</tt> returned by any such method is owned by the caller.
 103  * The caller may subsequently modify it; the service provider may not.
 104  *
 105  *
 106  *<h1>Environment Properties</h1>
 107  *<p>
 108  * JNDI applications need a way to communicate various preferences
 109  * and properties that define the environment in which naming and
 110  * directory services are accessed. For example, a context might
 111  * require specification of security credentials in order to access
 112  * the service. Another context might require that server configuration
 113  * information be supplied. These are referred to as the <em>environment</em>
 114  * of a context. The <tt>Context</tt> interface provides methods for
 115  * retrieving and updating this environment.
 116  *<p>
 117  * The environment is inherited from the parent context as
 118  * context methods proceed from one context to the next. Changes to
 119  * the environment of one context do not directly affect those
 120  * of other contexts.
 121  *<p>
 122  * It is implementation-dependent when environment properties are used
 123  * and/or verified for validity.  For example, some of the
 124  * security-related properties are used by service providers to "log in"
 125  * to the directory.  This login process might occur at the time the
 126  * context is created, or the first time a method is invoked on the
 127  * context.  When, and whether this occurs at all, is
 128  * implementation-dependent.  When environment properties are added or
 129  * removed from the context, verifying the validity of the changes is again
 130  * implementation-dependent. For example, verification of some properties
 131  * might occur at the time the change is made, or at the time the next
 132  * operation is performed on the context, or not at all.
 133  *<p>
 134  * Any object with a reference to a context may examine that context's
 135  * environment.  Sensitive information such as clear-text
 136  * passwords should not be stored there unless the implementation is
 137  * known to protect it.
 138  *
 139  *<p>
 140  *<a name=RESOURCEFILES></a>
 141  *<h1>Resource Files</h1>
 142  *<p>
 143  * To simplify the task of setting up the environment
 144  * required by a JNDI application,
 145  * application components and service providers may be distributed
 146  * along with <em>resource files.</em>
 147  * A JNDI resource file is a file in the properties file format (see
 148  * {@link java.util.Properties#load <tt>java.util.Properties</tt>}),
 149  * containing a list of key/value pairs.
 150  * The key is the name of the property (e.g. "java.naming.factory.object")
 151  * and the value is a string in the format defined
 152  * for that property.  Here is an example of a JNDI resource file:
 153  *
 154  * <blockquote>{@code
 155  * java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
 156  * java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
 157  * java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
 158  * }</blockquote>
 159  *
 160  * The JNDI class library reads the resource files and makes the property
 161  * values freely available.  Thus JNDI resource files should be considered
 162  * to be "world readable", and sensitive information such as clear-text
 163  * passwords should not be stored there.
 164  *<p>
 165  * There are two kinds of JNDI resource files:
 166  * <em>provider</em> and <em>application</em>.
 167  *
 168  * <h2>Provider Resource Files</h2>
 169  *
 170  * Each service provider has an optional resource that lists properties
 171  * specific to that provider.  The name of this resource is:
 172  * <blockquote>
 173  * [<em>prefix</em>/]<tt>jndiprovider.properties</tt>
 174  * </blockquote>
 175  * where <em>prefix</em> is
 176  * the package name of the provider's context implementation(s),
 177  * with each period (".") converted to a slash ("/").
 178  *
 179  * For example, suppose a service provider defines a context
 180  * implementation with class name <tt>com.sun.jndi.ldap.LdapCtx</tt>.
 181  * The provider resource for this provider is named
 182  * <tt>com/sun/jndi/ldap/jndiprovider.properties</tt>.  If the class is
 183  * not in a package, the resource's name is simply
 184  * <tt>jndiprovider.properties</tt>.
 185  *
 186  * <p>
 187  * <a name=LISTPROPS></a>
 188  * Certain methods in the JNDI class library make use of the standard
 189  * JNDI properties that specify lists of JNDI factories:
 190  * <ul>
 191  * <li>java.naming.factory.object
 192  * <li>java.naming.factory.state
 193  * <li>java.naming.factory.control
 194  * <li>java.naming.factory.url.pkgs
 195  * </ul>
 196  * The JNDI library will consult the provider resource file
 197  * when determining the values of these properties.
 198  * Properties other than these may be set in the provider
 199  * resource file at the discretion of the service provider.
 200  * The service provider's documentation should clearly state which
 201  * properties are allowed; other properties in the file will be ignored.
 202  *
 203  * <h2>Application Resource Files</h2>
 204  *
 205  * When an application is deployed, it will generally have several
 206  * codebase directories and JARs in its classpath. JNDI locates (using
 207  * {@link ClassLoader#getResources <tt>ClassLoader.getResources()</tt>})
 208  * all <em>application resource files</em> named <tt>jndi.properties</tt>
 209  * in the classpath.
 210  * In addition, if the file <i>java.home</i><tt>/lib/jndi.properties</tt>
 211  * exists and is readable,
 212  * JNDI treats it as an additional application resource file.
 213  * (<i>java.home</i> indicates the
 214  * directory named by the <tt>java.home</tt> system property.)
 215  * All of the properties contained in these files are placed
 216  * into the environment of the initial context.  This environment
 217  * is then inherited by other contexts.
 218  *
 219  * <p>
 220  * For each property found in more than one application resource file,
 221  * JNDI uses the first value found or, in a few cases where it makes
 222  * sense to do so, it concatenates all of the values (details are given
 223  * below).
 224  * For example, if the "java.naming.factory.object" property is found in
 225  * three <tt>jndi.properties</tt> resource files, the
 226  * list of object factories is a concatenation of the property
 227  * values from all three files.
 228  * Using this scheme, each deployable component is responsible for
 229  * listing the factories that it exports.  JNDI automatically
 230  * collects and uses all of these export lists when searching for factory
 231  * classes.
 232  *
 233  * <h2>Search Algorithm for Properties</h2>
 234  *
 235  * When JNDI constructs an initial context, the context's environment
 236  * is initialized with properties defined in the environment parameter
 237  * passed to the constructor, the system properties,
 238  * and the application resource files.  See
 239  * <a href=InitialContext.html#ENVIRONMENT><tt>InitialContext</tt></a>
 240  * for details.
 241  * This initial environment is then inherited by other context instances.
 242  *
 243  * <p>
 244  * When the JNDI class library needs to determine
 245  * the value of a property, it does so by merging
 246  * the values from the following two sources, in order:
 247  * <ol>
 248  * <li>The environment of the context being operated on.
 249  * <li>The provider resource file (<tt>jndiprovider.properties</tt>)
 250  * for the context being operated on.
 251  * </ol>
 252  * For each property found in both of these two sources,
 253  * JNDI determines the property's value as follows.  If the property is
 254  * one of the standard JNDI properties that specify a list of JNDI
 255  * factories (listed <a href=#LISTPROPS>above</a>), the values are
 256  * concatenated into a single colon-separated list.  For other
 257  * properties, only the first value found is used.
 258  *
 259  * <p>
 260  * When a service provider needs to determine the value of a property,
 261  * it will generally take that value directly from the environment.
 262  * A service provider may define provider-specific properties
 263  * to be placed in its own provider resource file.  In that
 264  * case it should merge values as described in the previous paragraph.
 265  *
 266  * <p>
 267  * In this way, each service provider developer can specify a list of
 268  * factories to use with that service provider. These can be modified by
 269  * the application resources specified by the deployer of the application,
 270  * which in turn can be modified by the user.
 271  *
 272  * @author Rosanna Lee
 273  * @author Scott Seligman
 274  * @author R. Vasudevan
 275  *
 276  * @since 1.3
 277  */
 278 
 279 public interface Context {
 280 
 281     /**
 282      * Retrieves the named object.
 283      * If <tt>name</tt> is empty, returns a new instance of this context
 284      * (which represents the same naming context as this context, but its
 285      * environment may be modified independently and it may be accessed
 286      * concurrently).
 287      *
 288      * @param name
 289      *          the name of the object to look up
 290      * @return  the object bound to <tt>name</tt>
 291      * @throws  NamingException if a naming exception is encountered
 292      *
 293      * @see #lookup(String)
 294      * @see #lookupLink(Name)
 295      */
 296     public Object lookup(Name name) throws NamingException;
 297 
 298     /**
 299      * Retrieves the named object.
 300      * See {@link #lookup(Name)} for details.
 301      * @param name
 302      *          the name of the object to look up
 303      * @return  the object bound to <tt>name</tt>
 304      * @throws  NamingException if a naming exception is encountered
 305      */
 306     public Object lookup(String name) throws NamingException;
 307 
 308     /**
 309      * Binds a name to an object.
 310      * All intermediate contexts and the target context (that named by all
 311      * but terminal atomic component of the name) must already exist.
 312      *
 313      * @param name
 314      *          the name to bind; may not be empty
 315      * @param obj
 316      *          the object to bind; possibly null
 317      * @throws  NameAlreadyBoundException if name is already bound
 318      * @throws  javax.naming.directory.InvalidAttributesException
 319      *          if object did not supply all mandatory attributes
 320      * @throws  NamingException if a naming exception is encountered
 321      *
 322      * @see #bind(String, Object)
 323      * @see #rebind(Name, Object)
 324      * @see javax.naming.directory.DirContext#bind(Name, Object,
 325      *          javax.naming.directory.Attributes)
 326      */
 327     public void bind(Name name, Object obj) throws NamingException;
 328 
 329     /**
 330      * Binds a name to an object.
 331      * See {@link #bind(Name, Object)} for details.
 332      *
 333      * @param name
 334      *          the name to bind; may not be empty
 335      * @param obj
 336      *          the object to bind; possibly null
 337      * @throws  NameAlreadyBoundException if name is already bound
 338      * @throws  javax.naming.directory.InvalidAttributesException
 339      *          if object did not supply all mandatory attributes
 340      * @throws  NamingException if a naming exception is encountered
 341      */
 342     public void bind(String name, Object obj) throws NamingException;
 343 
 344     /**
 345      * Binds a name to an object, overwriting any existing binding.
 346      * All intermediate contexts and the target context (that named by all
 347      * but terminal atomic component of the name) must already exist.
 348      *
 349      * <p> If the object is a <tt>DirContext</tt>, any existing attributes
 350      * associated with the name are replaced with those of the object.
 351      * Otherwise, any existing attributes associated with the name remain
 352      * unchanged.
 353      *
 354      * @param name
 355      *          the name to bind; may not be empty
 356      * @param obj
 357      *          the object to bind; possibly null
 358      * @throws  javax.naming.directory.InvalidAttributesException
 359      *          if object did not supply all mandatory attributes
 360      * @throws  NamingException if a naming exception is encountered
 361      *
 362      * @see #rebind(String, Object)
 363      * @see #bind(Name, Object)
 364      * @see javax.naming.directory.DirContext#rebind(Name, Object,
 365      *          javax.naming.directory.Attributes)
 366      * @see javax.naming.directory.DirContext
 367      */
 368     public void rebind(Name name, Object obj) throws NamingException;
 369 
 370     /**
 371      * Binds a name to an object, overwriting any existing binding.
 372      * See {@link #rebind(Name, Object)} for details.
 373      *
 374      * @param name
 375      *          the name to bind; may not be empty
 376      * @param obj
 377      *          the object to bind; possibly null
 378      * @throws  javax.naming.directory.InvalidAttributesException
 379      *          if object did not supply all mandatory attributes
 380      * @throws  NamingException if a naming exception is encountered
 381      */
 382     public void rebind(String name, Object obj) throws NamingException;
 383 
 384     /**
 385      * Unbinds the named object.
 386      * Removes the terminal atomic name in <code>name</code>
 387      * from the target context--that named by all but the terminal
 388      * atomic part of <code>name</code>.
 389      *
 390      * <p> This method is idempotent.
 391      * It succeeds even if the terminal atomic name
 392      * is not bound in the target context, but throws
 393      * <tt>NameNotFoundException</tt>
 394      * if any of the intermediate contexts do not exist.
 395      *
 396      * <p> Any attributes associated with the name are removed.
 397      * Intermediate contexts are not changed.
 398      *
 399      * @param name
 400      *          the name to unbind; may not be empty
 401      * @throws  NameNotFoundException if an intermediate context does not exist
 402      * @throws  NamingException if a naming exception is encountered
 403      * @see #unbind(String)
 404      */
 405     public void unbind(Name name) throws NamingException;
 406 
 407     /**
 408      * Unbinds the named object.
 409      * See {@link #unbind(Name)} for details.
 410      *
 411      * @param name
 412      *          the name to unbind; may not be empty
 413      * @throws  NameNotFoundException if an intermediate context does not exist
 414      * @throws  NamingException if a naming exception is encountered
 415      */
 416     public void unbind(String name) throws NamingException;
 417 
 418     /**
 419      * Binds a new name to the object bound to an old name, and unbinds
 420      * the old name.  Both names are relative to this context.
 421      * Any attributes associated with the old name become associated
 422      * with the new name.
 423      * Intermediate contexts of the old name are not changed.
 424      *
 425      * @param oldName
 426      *          the name of the existing binding; may not be empty
 427      * @param newName
 428      *          the name of the new binding; may not be empty
 429      * @throws  NameAlreadyBoundException if <tt>newName</tt> is already bound
 430      * @throws  NamingException if a naming exception is encountered
 431      *
 432      * @see #rename(String, String)
 433      * @see #bind(Name, Object)
 434      * @see #rebind(Name, Object)
 435      */
 436     public void rename(Name oldName, Name newName) throws NamingException;
 437 
 438     /**
 439      * Binds a new name to the object bound to an old name, and unbinds
 440      * the old name.
 441      * See {@link #rename(Name, Name)} for details.
 442      *
 443      * @param oldName
 444      *          the name of the existing binding; may not be empty
 445      * @param newName
 446      *          the name of the new binding; may not be empty
 447      * @throws  NameAlreadyBoundException if <tt>newName</tt> is already bound
 448      * @throws  NamingException if a naming exception is encountered
 449      */
 450     public void rename(String oldName, String newName) throws NamingException;
 451 
 452     /**
 453      * Enumerates the names bound in the named context, along with the
 454      * class names of objects bound to them.
 455      * The contents of any subcontexts are not included.
 456      *
 457      * <p> If a binding is added to or removed from this context,
 458      * its effect on an enumeration previously returned is undefined.
 459      *
 460      * @param name
 461      *          the name of the context to list
 462      * @return  an enumeration of the names and class names of the
 463      *          bindings in this context.  Each element of the
 464      *          enumeration is of type <tt>NameClassPair</tt>.
 465      * @throws  NamingException if a naming exception is encountered
 466      *
 467      * @see #list(String)
 468      * @see #listBindings(Name)
 469      * @see NameClassPair
 470      */
 471     public NamingEnumeration<NameClassPair> list(Name name)
 472         throws NamingException;
 473 
 474     /**
 475      * Enumerates the names bound in the named context, along with the
 476      * class names of objects bound to them.
 477      * See {@link #list(Name)} for details.
 478      *
 479      * @param name
 480      *          the name of the context to list
 481      * @return  an enumeration of the names and class names of the
 482      *          bindings in this context.  Each element of the
 483      *          enumeration is of type <tt>NameClassPair</tt>.
 484      * @throws  NamingException if a naming exception is encountered
 485      */
 486     public NamingEnumeration<NameClassPair> list(String name)
 487         throws NamingException;
 488 
 489     /**
 490      * Enumerates the names bound in the named context, along with the
 491      * objects bound to them.
 492      * The contents of any subcontexts are not included.
 493      *
 494      * <p> If a binding is added to or removed from this context,
 495      * its effect on an enumeration previously returned is undefined.
 496      *
 497      * @param name
 498      *          the name of the context to list
 499      * @return  an enumeration of the bindings in this context.
 500      *          Each element of the enumeration is of type
 501      *          <tt>Binding</tt>.
 502      * @throws  NamingException if a naming exception is encountered
 503      *
 504      * @see #listBindings(String)
 505      * @see #list(Name)
 506      * @see Binding
 507       */
 508     public NamingEnumeration<Binding> listBindings(Name name)
 509         throws NamingException;
 510 
 511     /**
 512      * Enumerates the names bound in the named context, along with the
 513      * objects bound to them.
 514      * See {@link #listBindings(Name)} for details.
 515      *
 516      * @param name
 517      *          the name of the context to list
 518      * @return  an enumeration of the bindings in this context.
 519      *          Each element of the enumeration is of type
 520      *          <tt>Binding</tt>.
 521      * @throws  NamingException if a naming exception is encountered
 522      */
 523     public NamingEnumeration<Binding> listBindings(String name)
 524         throws NamingException;
 525 
 526     /**
 527      * Destroys the named context and removes it from the namespace.
 528      * Any attributes associated with the name are also removed.
 529      * Intermediate contexts are not destroyed.
 530      *
 531      * <p> This method is idempotent.
 532      * It succeeds even if the terminal atomic name
 533      * is not bound in the target context, but throws
 534      * <tt>NameNotFoundException</tt>
 535      * if any of the intermediate contexts do not exist.
 536      *
 537      * <p> In a federated naming system, a context from one naming system
 538      * may be bound to a name in another.  One can subsequently
 539      * look up and perform operations on the foreign context using a
 540      * composite name.  However, an attempt destroy the context using
 541      * this composite name will fail with
 542      * <tt>NotContextException</tt>, because the foreign context is not
 543      * a "subcontext" of the context in which it is bound.
 544      * Instead, use <tt>unbind()</tt> to remove the
 545      * binding of the foreign context.  Destroying the foreign context
 546      * requires that the <tt>destroySubcontext()</tt> be performed
 547      * on a context from the foreign context's "native" naming system.
 548      *
 549      * @param name
 550      *          the name of the context to be destroyed; may not be empty
 551      * @throws  NameNotFoundException if an intermediate context does not exist
 552      * @throws  NotContextException if the name is bound but does not name a
 553      *          context, or does not name a context of the appropriate type
 554      * @throws  ContextNotEmptyException if the named context is not empty
 555      * @throws  NamingException if a naming exception is encountered
 556      *
 557      * @see #destroySubcontext(String)
 558      */
 559     public void destroySubcontext(Name name) throws NamingException;
 560 
 561     /**
 562      * Destroys the named context and removes it from the namespace.
 563      * See {@link #destroySubcontext(Name)} for details.
 564      *
 565      * @param name
 566      *          the name of the context to be destroyed; may not be empty
 567      * @throws  NameNotFoundException if an intermediate context does not exist
 568      * @throws  NotContextException if the name is bound but does not name a
 569      *          context, or does not name a context of the appropriate type
 570      * @throws  ContextNotEmptyException if the named context is not empty
 571      * @throws  NamingException if a naming exception is encountered
 572      */
 573     public void destroySubcontext(String name) throws NamingException;
 574 
 575     /**
 576      * Creates and binds a new context.
 577      * Creates a new context with the given name and binds it in
 578      * the target context (that named by all but terminal atomic
 579      * component of the name).  All intermediate contexts and the
 580      * target context must already exist.
 581      *
 582      * @param name
 583      *          the name of the context to create; may not be empty
 584      * @return  the newly created context
 585      *
 586      * @throws  NameAlreadyBoundException if name is already bound
 587      * @throws  javax.naming.directory.InvalidAttributesException
 588      *          if creation of the subcontext requires specification of
 589      *          mandatory attributes
 590      * @throws  NamingException if a naming exception is encountered
 591      *
 592      * @see #createSubcontext(String)
 593      * @see javax.naming.directory.DirContext#createSubcontext
 594      */
 595     public Context createSubcontext(Name name) throws NamingException;
 596 
 597     /**
 598      * Creates and binds a new context.
 599      * See {@link #createSubcontext(Name)} for details.
 600      *
 601      * @param name
 602      *          the name of the context to create; may not be empty
 603      * @return  the newly created context
 604      *
 605      * @throws  NameAlreadyBoundException if name is already bound
 606      * @throws  javax.naming.directory.InvalidAttributesException
 607      *          if creation of the subcontext requires specification of
 608      *          mandatory attributes
 609      * @throws  NamingException if a naming exception is encountered
 610      */
 611     public Context createSubcontext(String name) throws NamingException;
 612 
 613     /**
 614      * Retrieves the named object, following links except
 615      * for the terminal atomic component of the name.
 616      * If the object bound to <tt>name</tt> is not a link,
 617      * returns the object itself.
 618      *
 619      * @param name
 620      *          the name of the object to look up
 621      * @return  the object bound to <tt>name</tt>, not following the
 622      *          terminal link (if any).
 623      * @throws  NamingException if a naming exception is encountered
 624      *
 625      * @see #lookupLink(String)
 626      */
 627     public Object lookupLink(Name name) throws NamingException;
 628 
 629     /**
 630      * Retrieves the named object, following links except
 631      * for the terminal atomic component of the name.
 632      * See {@link #lookupLink(Name)} for details.
 633      *
 634      * @param name
 635      *          the name of the object to look up
 636      * @return  the object bound to <tt>name</tt>, not following the
 637      *          terminal link (if any)
 638      * @throws  NamingException if a naming exception is encountered
 639      */
 640     public Object lookupLink(String name) throws NamingException;
 641 
 642     /**
 643      * Retrieves the parser associated with the named context.
 644      * In a federation of namespaces, different naming systems will
 645      * parse names differently.  This method allows an application
 646      * to get a parser for parsing names into their atomic components
 647      * using the naming convention of a particular naming system.
 648      * Within any single naming system, <tt>NameParser</tt> objects
 649      * returned by this method must be equal (using the <tt>equals()</tt>
 650      * test).
 651      *
 652      * @param name
 653      *          the name of the context from which to get the parser
 654      * @return  a name parser that can parse compound names into their atomic
 655      *          components
 656      * @throws  NamingException if a naming exception is encountered
 657      *
 658      * @see #getNameParser(String)
 659      * @see CompoundName
 660      */
 661     public NameParser getNameParser(Name name) throws NamingException;
 662 
 663     /**
 664      * Retrieves the parser associated with the named context.
 665      * See {@link #getNameParser(Name)} for details.
 666      *
 667      * @param name
 668      *          the name of the context from which to get the parser
 669      * @return  a name parser that can parse compound names into their atomic
 670      *          components
 671      * @throws  NamingException if a naming exception is encountered
 672      */
 673     public NameParser getNameParser(String name) throws NamingException;
 674 
 675     /**
 676      * Composes the name of this context with a name relative to
 677      * this context.
 678      * Given a name (<code>name</code>) relative to this context, and
 679      * the name (<code>prefix</code>) of this context relative to one
 680      * of its ancestors, this method returns the composition of the
 681      * two names using the syntax appropriate for the naming
 682      * system(s) involved.  That is, if <code>name</code> names an
 683      * object relative to this context, the result is the name of the
 684      * same object, but relative to the ancestor context.  None of the
 685      * names may be null.
 686      * <p>
 687      * For example, if this context is named "wiz.com" relative
 688      * to the initial context, then
 689      * <pre>
 690      *  composeName("east", "wiz.com")  </pre>
 691      * might return <code>"east.wiz.com"</code>.
 692      * If instead this context is named "org/research", then
 693      * <pre>
 694      *  composeName("user/jane", "org/research")        </pre>
 695      * might return <code>"org/research/user/jane"</code> while
 696      * <pre>
 697      *  composeName("user/jane", "research")    </pre>
 698      * returns <code>"research/user/jane"</code>.
 699      *
 700      * @param name
 701      *          a name relative to this context
 702      * @param prefix
 703      *          the name of this context relative to one of its ancestors
 704      * @return  the composition of <code>prefix</code> and <code>name</code>
 705      * @throws  NamingException if a naming exception is encountered
 706      *
 707      * @see #composeName(String, String)
 708      */
 709     public Name composeName(Name name, Name prefix)
 710         throws NamingException;
 711 
 712     /**
 713      * Composes the name of this context with a name relative to
 714      * this context.
 715      * See {@link #composeName(Name, Name)} for details.
 716      *
 717      * @param name
 718      *          a name relative to this context
 719      * @param prefix
 720      *          the name of this context relative to one of its ancestors
 721      * @return  the composition of <code>prefix</code> and <code>name</code>
 722      * @throws  NamingException if a naming exception is encountered
 723      */
 724     public String composeName(String name, String prefix)
 725             throws NamingException;
 726 
 727     /**
 728      * Adds a new environment property to the environment of this
 729      * context.  If the property already exists, its value is overwritten.
 730      * See class description for more details on environment properties.
 731      *
 732      * @param propName
 733      *          the name of the environment property to add; may not be null
 734      * @param propVal
 735      *          the value of the property to add; may not be null
 736      * @return  the previous value of the property, or null if the property was
 737      *          not in the environment before
 738      * @throws  NamingException if a naming exception is encountered
 739      *
 740      * @see #getEnvironment()
 741      * @see #removeFromEnvironment(String)
 742      */
 743     public Object addToEnvironment(String propName, Object propVal)
 744         throws NamingException;
 745 
 746     /**
 747      * Removes an environment property from the environment of this
 748      * context.  See class description for more details on environment
 749      * properties.
 750      *
 751      * @param propName
 752      *          the name of the environment property to remove; may not be null
 753      * @return  the previous value of the property, or null if the property was
 754      *          not in the environment
 755      * @throws  NamingException if a naming exception is encountered
 756      *
 757      * @see #getEnvironment()
 758      * @see #addToEnvironment(String, Object)
 759      */
 760     public Object removeFromEnvironment(String propName)
 761         throws NamingException;
 762 
 763     /**
 764      * Retrieves the environment in effect for this context.
 765      * See class description for more details on environment properties.
 766      *
 767      * <p> The caller should not make any changes to the object returned:
 768      * their effect on the context is undefined.
 769      * The environment of this context may be changed using
 770      * <tt>addToEnvironment()</tt> and <tt>removeFromEnvironment()</tt>.
 771      *
 772      * @return  the environment of this context; never null
 773      * @throws  NamingException if a naming exception is encountered
 774      *
 775      * @see #addToEnvironment(String, Object)
 776      * @see #removeFromEnvironment(String)
 777      */
 778     public Hashtable<?,?> getEnvironment() throws NamingException;
 779 
 780     /**
 781      * Closes this context.
 782      * This method releases this context's resources immediately, instead of
 783      * waiting for them to be released automatically by the garbage collector.
 784      *
 785      * <p> This method is idempotent:  invoking it on a context that has
 786      * already been closed has no effect.  Invoking any other method
 787      * on a closed context is not allowed, and results in undefined behaviour.
 788      *
 789      * @throws  NamingException if a naming exception is encountered
 790      */
 791     public void close() throws NamingException;
 792 
 793     /**
 794      * Retrieves the full name of this context within its own namespace.
 795      *
 796      * <p> Many naming services have a notion of a "full name" for objects
 797      * in their respective namespaces.  For example, an LDAP entry has
 798      * a distinguished name, and a DNS record has a fully qualified name.
 799      * This method allows the client application to retrieve this name.
 800      * The string returned by this method is not a JNDI composite name
 801      * and should not be passed directly to context methods.
 802      * In naming systems for which the notion of full name does not
 803      * make sense, <tt>OperationNotSupportedException</tt> is thrown.
 804      *
 805      * @return  this context's name in its own namespace; never null
 806      * @throws  OperationNotSupportedException if the naming system does
 807      *          not have the notion of a full name
 808      * @throws  NamingException if a naming exception is encountered
 809      *
 810      * @since 1.3
 811      */
 812     public String getNameInNamespace() throws NamingException;
 813 
 814 // public static final:  JLS says recommended style is to omit these modifiers
 815 // because they are the default
 816 
 817     /**
 818      * Constant that holds the name of the environment property
 819      * for specifying the initial context factory to use. The value
 820      * of the property should be the fully qualified class name
 821      * of the factory class that will create an initial context.
 822      * This property may be specified in the environment parameter
 823      * passed to the initial context constructor,
 824      * a system property, or an application resource file.
 825      * If it is not specified in any of these sources,
 826      * <tt>NoInitialContextException</tt> is thrown when an initial
 827      * context is required to complete an operation.
 828      *
 829      * <p> The value of this constant is "java.naming.factory.initial".
 830      *
 831      * @see InitialContext
 832      * @see javax.naming.directory.InitialDirContext
 833      * @see javax.naming.spi.NamingManager#getInitialContext
 834      * @see javax.naming.spi.InitialContextFactory
 835      * @see NoInitialContextException
 836      * @see #addToEnvironment(String, Object)
 837      * @see #removeFromEnvironment(String)
 838      */
 839     String INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial";
 840 
 841     /**
 842      * Constant that holds the name of the environment property
 843      * for specifying the list of object factories to use. The value
 844      * of the property should be a colon-separated list of the fully
 845      * qualified class names of factory classes that will create an object
 846      * given information about the object.
 847      * This property may be specified in the environment, a system property,
 848      * or one or more resource files.
 849      *
 850      * <p> The value of this constant is "java.naming.factory.object".
 851      *
 852      * @see javax.naming.spi.NamingManager#getObjectInstance
 853      * @see javax.naming.spi.ObjectFactory
 854      * @see #addToEnvironment(String, Object)
 855      * @see #removeFromEnvironment(String)
 856      */
 857     String OBJECT_FACTORIES = "java.naming.factory.object";
 858 
 859     /**
 860      * Constant that holds the name of the environment property
 861      * for specifying the list of state factories to use. The value
 862      * of the property should be a colon-separated list of the fully
 863      * qualified class names of state factory classes that will be used
 864      * to get an object's state given the object itself.
 865      * This property may be specified in the environment, a system property,
 866      * or one or more resource files.
 867      *
 868      * <p> The value of this constant is "java.naming.factory.state".
 869      *
 870      * @see javax.naming.spi.NamingManager#getStateToBind
 871      * @see javax.naming.spi.StateFactory
 872      * @see #addToEnvironment(String, Object)
 873      * @see #removeFromEnvironment(String)
 874      * @since 1.3
 875      */
 876     String STATE_FACTORIES = "java.naming.factory.state";
 877 
 878     /**
 879      * Constant that holds the name of the environment property
 880      * for specifying the list of package prefixes to use when
 881      * loading in URL context factories. The value
 882      * of the property should be a colon-separated list of package
 883      * prefixes for the class name of the factory class that will create
 884      * a URL context factory.
 885      * This property may be specified in the environment, a system property,
 886      * or one or more resource files.
 887      * The prefix <tt>com.sun.jndi.url</tt> is always appended to
 888      * the possibly empty list of package prefixes.
 889      *
 890      * <p> The value of this constant is "java.naming.factory.url.pkgs".
 891      *
 892      * @see javax.naming.spi.NamingManager#getObjectInstance
 893      * @see javax.naming.spi.NamingManager#getURLContext
 894      * @see javax.naming.spi.ObjectFactory
 895      * @see #addToEnvironment(String, Object)
 896      * @see #removeFromEnvironment(String)
 897      */
 898     String URL_PKG_PREFIXES = "java.naming.factory.url.pkgs";
 899 
 900     /**
 901      * Constant that holds the name of the environment property
 902      * for specifying configuration information for the service provider
 903      * to use. The value of the property should contain a URL string
 904      * (e.g. "ldap://somehost:389").
 905      * This property may be specified in the environment, a system property,
 906      * or a resource file.
 907      * If it is not specified in any of these sources,
 908      * the default configuration is determined by the service provider.
 909      *
 910      * <p> The value of this constant is "java.naming.provider.url".
 911      *
 912      * @see #addToEnvironment(String, Object)
 913      * @see #removeFromEnvironment(String)
 914      */
 915     String PROVIDER_URL = "java.naming.provider.url";
 916 
 917     /**
 918      * Constant that holds the name of the environment property
 919      * for specifying the DNS host and domain names to use for the
 920      * JNDI URL context (for example, "dns://somehost/wiz.com").
 921      * This property may be specified in the environment, a system property,
 922      * or a resource file.
 923      * If it is not specified in any of these sources
 924      * and the program attempts to use a JNDI URL containing a DNS name,
 925      * a <tt>ConfigurationException</tt> will be thrown.
 926      *
 927      * <p> The value of this constant is "java.naming.dns.url".
 928      *
 929      * @see #addToEnvironment(String, Object)
 930      * @see #removeFromEnvironment(String)
 931      */
 932     String DNS_URL = "java.naming.dns.url";
 933 
 934     /**
 935      * Constant that holds the name of the environment property for
 936      * specifying the authoritativeness of the service requested.
 937      * If the value of the property is the string "true", it means
 938      * that the access is to the most authoritative source (i.e. bypass
 939      * any cache or replicas). If the value is anything else,
 940      * the source need not be (but may be) authoritative.
 941      * If unspecified, the value defaults to "false".
 942      *
 943      * <p> The value of this constant is "java.naming.authoritative".
 944      *
 945      * @see #addToEnvironment(String, Object)
 946      * @see #removeFromEnvironment(String)
 947      */
 948     String AUTHORITATIVE = "java.naming.authoritative";
 949 
 950     /**
 951      * Constant that holds the name of the environment property for
 952      * specifying the batch size to use when returning data via the
 953      * service's protocol. This is a hint to the provider to return
 954      * the results of operations in batches of the specified size, so
 955      * the provider can optimize its performance and usage of resources.
 956      * The value of the property is the string representation of an
 957      * integer.
 958      * If unspecified, the batch size is determined by the service
 959      * provider.
 960      *
 961      * <p> The value of this constant is "java.naming.batchsize".
 962      *
 963      * @see #addToEnvironment(String, Object)
 964      * @see #removeFromEnvironment(String)
 965      */
 966     String BATCHSIZE = "java.naming.batchsize";
 967 
 968     /**
 969      * Constant that holds the name of the environment property for
 970      * specifying how referrals encountered by the service provider
 971      * are to be processed. The value of the property is one of the
 972      * following strings:
 973      * <dl>
 974      * <dt>"follow"
 975      * <dd>follow referrals automatically
 976      * <dt>"ignore"
 977      * <dd>ignore referrals
 978      * <dt>"throw"
 979      * <dd>throw <tt>ReferralException</tt> when a referral is encountered.
 980      * </dl>
 981      * If this property is not specified, the default is
 982      * determined by the provider.
 983      *
 984      * <p> The value of this constant is "java.naming.referral".
 985      *
 986      * @see #addToEnvironment(String, Object)
 987      * @see #removeFromEnvironment(String)
 988      */
 989     String REFERRAL = "java.naming.referral";
 990 
 991     /**
 992      * Constant that holds the name of the environment property for
 993      * specifying the security protocol to use.
 994      * Its value is a string determined by the service provider
 995      * (e.g. "ssl").
 996      * If this property is unspecified,
 997      * the behaviour is determined by the service provider.
 998      *
 999      * <p> The value of this constant is "java.naming.security.protocol".
1000      *
1001      * @see #addToEnvironment(String, Object)
1002      * @see #removeFromEnvironment(String)
1003      */
1004     String SECURITY_PROTOCOL = "java.naming.security.protocol";
1005 
1006     /**
1007      * Constant that holds the name of the environment property for
1008      * specifying the security level to use.
1009      * Its value is one of the following strings:
1010      * "none", "simple", "strong".
1011      * If this property is unspecified,
1012      * the behaviour is determined by the service provider.
1013      *
1014      * <p> The value of this constant is "java.naming.security.authentication".
1015      *
1016      * @see #addToEnvironment(String, Object)
1017      * @see #removeFromEnvironment(String)
1018      */
1019     String SECURITY_AUTHENTICATION = "java.naming.security.authentication";
1020 
1021     /**
1022      * Constant that holds the name of the environment property for
1023      * specifying the identity of the principal for authenticating
1024      * the caller to the service. The format of the principal
1025      * depends on the authentication scheme.
1026      * If this property is unspecified,
1027      * the behaviour is determined by the service provider.
1028      *
1029      * <p> The value of this constant is "java.naming.security.principal".
1030      *
1031      * @see #addToEnvironment(String, Object)
1032      * @see #removeFromEnvironment(String)
1033      */
1034     String SECURITY_PRINCIPAL = "java.naming.security.principal";
1035 
1036     /**
1037      * Constant that holds the name of the environment property for
1038      * specifying the credentials of the principal for authenticating
1039      * the caller to the service. The value of the property depends
1040      * on the authentication scheme. For example, it could be a hashed
1041      * password, clear-text password, key, certificate, and so on.
1042      * If this property is unspecified,
1043      * the behaviour is determined by the service provider.
1044      *
1045      * <p> The value of this constant is "java.naming.security.credentials".
1046      *
1047      * @see #addToEnvironment(String, Object)
1048      * @see #removeFromEnvironment(String)
1049      */
1050 
1051     String SECURITY_CREDENTIALS = "java.naming.security.credentials";
1052     /**
1053      * Constant that holds the name of the environment property for
1054      * specifying the preferred language to use with the service.
1055      * The value of the property is a colon-separated list of language
1056      * tags as defined in RFC 1766.
1057      * If this property is unspecified,
1058      * the language preference is determined by the service provider.
1059      *
1060      * <p> The value of this constant is "java.naming.language".
1061      *
1062      * @see #addToEnvironment(String, Object)
1063      * @see #removeFromEnvironment(String)
1064      */
1065     String LANGUAGE = "java.naming.language";
1066 
1067     /**
1068      * @deprecated An environment property with this name is ignored
1069      *             while constructing an initial context.
1070      * This constant was originally used as a property name to specify an
1071      * {@code Applet} to retrieve parameters from, when creating an initial
1072      * context. Currently any applet properties that need to be passed to an
1073      * initial context should be copied into the environment hashtable:
1074      * <pre>{@code
1075      *     Hashtable env = new Hashtable();
1076      *     env.put(Context.INITIAL_CONTEXT_FACTORY,
1077      *       ((Applet) this).getParameter(Context.INITIAL_CONTEXT_FACTORY));
1078      *     env.put(Context.PROVIDER_URL,
1079      *       ((Applet) this).getParameter(Context.PROVIDER_URL));
1080      *     // ... other properties ...
1081      *
1082      *     Context ctx = new InitialContext(env);
1083      * }</pre>
1084      *
1085      * @since 1.3
1086      */
1087     @Deprecated
1088     String APPLET = "java.naming.applet";
1089 };