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 };