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 {@code Context} 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, {@code String} name arguments to 51 * {@code Context} methods are composite names. Name arguments that are 52 * instances of {@code CompositeName} are treated as composite names, 53 * while {@code Name} arguments that are not instances of 54 * {@code CompositeName} are treated as compound names (which might be 55 * instances of {@code CompoundName} or other implementations of compound 56 * names). This allows the results of {@code NameParser.parse()} to be used as 57 * arguments to the {@code Context} 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 {@code NamingEnumeration} 62 * from {@code list()} and {@code listBindings()} are composite names 63 * represented as strings. 64 * See {@code CompositeName} for the string syntax of names. 65 *<p> 66 * For systems that do not support federation, the name arguments (in 67 * either {@code Name} or {@code String} forms) and the names returned in 68 * {@code NamingEnumeration} 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 {@code NamingException} or 74 * any of its subclasses. See {@code NamingException} 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) lookup} 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 {@code NamingEnumeration} 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 {@code Name} parameter passed to any method of the 96 * {@code Context} 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 {@code Name} 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 {@code Context} 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 java.util.Properties}), 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>/]{@code jndiprovider.properties} 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 {@code com.sun.jndi.ldap.LdapCtx}. 181 * The provider resource for this provider is named 182 * {@code com/sun/jndi/ldap/jndiprovider.properties}. If the class is 183 * not in a package, the resource's name is simply 184 * {@code jndiprovider.properties}. 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 ClassLoader.getResources()}) 208 * all <em>application resource files</em> named {@code jndi.properties} 209 * in the classpath. 210 * In addition, if the Java installation directory contains a built-in 211 * properties file, typically {@code conf/jndi.properties}, 212 * JNDI treats it as an additional application resource file. 213 * All of the properties contained in these files are placed 214 * into the environment of the initial context. This environment 215 * is then inherited by other contexts. 216 * 217 * <p> 218 * For each property found in more than one application resource file, 219 * JNDI uses the first value found or, in a few cases where it makes 220 * sense to do so, it concatenates all of the values (details are given 221 * below). 222 * For example, if the "java.naming.factory.object" property is found in 223 * three {@code jndi.properties} resource files, the 224 * list of object factories is a concatenation of the property 225 * values from all three files. 226 * Using this scheme, each deployable component is responsible for 227 * listing the factories that it exports. JNDI automatically 228 * collects and uses all of these export lists when searching for factory 229 * classes. 230 * 231 * <h2>Search Algorithm for Properties</h2> 232 * 233 * When JNDI constructs an initial context, the context's environment 234 * is initialized with properties defined in the environment parameter 235 * passed to the constructor, the system properties, 236 * and the application resource files. See 237 * <a href=InitialContext.html#ENVIRONMENT>{@code InitialContext}</a> 238 * for details. 239 * This initial environment is then inherited by other context instances. 240 * 241 * <p> 242 * When the JNDI class library needs to determine 243 * the value of a property, it does so by merging 244 * the values from the following two sources, in order: 245 * <ol> 246 * <li>The environment of the context being operated on. 247 * <li>The provider resource file ({@code jndiprovider.properties}) 248 * for the context being operated on. 249 * </ol> 250 * For each property found in both of these two sources, 251 * JNDI determines the property's value as follows. If the property is 252 * one of the standard JNDI properties that specify a list of JNDI 253 * factories (listed <a href=#LISTPROPS>above</a>), the values are 254 * concatenated into a single colon-separated list. For other 255 * properties, only the first value found is used. 256 * 257 * <p> 258 * When a service provider needs to determine the value of a property, 259 * it will generally take that value directly from the environment. 260 * A service provider may define provider-specific properties 261 * to be placed in its own provider resource file. In that 262 * case it should merge values as described in the previous paragraph. 263 * 264 * <p> 265 * In this way, each service provider developer can specify a list of 266 * factories to use with that service provider. These can be modified by 267 * the application resources specified by the deployer of the application, 268 * which in turn can be modified by the user. 269 * 270 * @author Rosanna Lee 271 * @author Scott Seligman 272 * @author R. Vasudevan 273 * 274 * @since 1.3 275 */ 276 277 public interface Context { 278 279 /** 280 * Retrieves the named object. 281 * If {@code name} is empty, returns a new instance of this context 282 * (which represents the same naming context as this context, but its 283 * environment may be modified independently and it may be accessed 284 * concurrently). 285 * 286 * @param name 287 * the name of the object to look up 288 * @return the object bound to {@code name} 289 * @throws NamingException if a naming exception is encountered 290 * 291 * @see #lookup(String) 292 * @see #lookupLink(Name) 293 */ 294 public Object lookup(Name name) throws NamingException; 295 296 /** 297 * Retrieves the named object. 298 * See {@link #lookup(Name)} for details. 299 * @param name 300 * the name of the object to look up 301 * @return the object bound to {@code name} 302 * @throws NamingException if a naming exception is encountered 303 */ 304 public Object lookup(String name) throws NamingException; 305 306 /** 307 * Binds a name to an object. 308 * All intermediate contexts and the target context (that named by all 309 * but terminal atomic component of the name) must already exist. 310 * 311 * @param name 312 * the name to bind; may not be empty 313 * @param obj 314 * the object to bind; possibly null 315 * @throws NameAlreadyBoundException if name is already bound 316 * @throws javax.naming.directory.InvalidAttributesException 317 * if object did not supply all mandatory attributes 318 * @throws NamingException if a naming exception is encountered 319 * 320 * @see #bind(String, Object) 321 * @see #rebind(Name, Object) 322 * @see javax.naming.directory.DirContext#bind(Name, Object, 323 * javax.naming.directory.Attributes) 324 */ 325 public void bind(Name name, Object obj) throws NamingException; 326 327 /** 328 * Binds a name to an object. 329 * See {@link #bind(Name, Object)} for details. 330 * 331 * @param name 332 * the name to bind; may not be empty 333 * @param obj 334 * the object to bind; possibly null 335 * @throws NameAlreadyBoundException if name is already bound 336 * @throws javax.naming.directory.InvalidAttributesException 337 * if object did not supply all mandatory attributes 338 * @throws NamingException if a naming exception is encountered 339 */ 340 public void bind(String name, Object obj) throws NamingException; 341 342 /** 343 * Binds a name to an object, overwriting any existing binding. 344 * All intermediate contexts and the target context (that named by all 345 * but terminal atomic component of the name) must already exist. 346 * 347 * <p> If the object is a {@code DirContext}, any existing attributes 348 * associated with the name are replaced with those of the object. 349 * Otherwise, any existing attributes associated with the name remain 350 * unchanged. 351 * 352 * @param name 353 * the name to bind; may not be empty 354 * @param obj 355 * the object to bind; possibly null 356 * @throws javax.naming.directory.InvalidAttributesException 357 * if object did not supply all mandatory attributes 358 * @throws NamingException if a naming exception is encountered 359 * 360 * @see #rebind(String, Object) 361 * @see #bind(Name, Object) 362 * @see javax.naming.directory.DirContext#rebind(Name, Object, 363 * javax.naming.directory.Attributes) 364 * @see javax.naming.directory.DirContext 365 */ 366 public void rebind(Name name, Object obj) throws NamingException; 367 368 /** 369 * Binds a name to an object, overwriting any existing binding. 370 * See {@link #rebind(Name, Object)} for details. 371 * 372 * @param name 373 * the name to bind; may not be empty 374 * @param obj 375 * the object to bind; possibly null 376 * @throws javax.naming.directory.InvalidAttributesException 377 * if object did not supply all mandatory attributes 378 * @throws NamingException if a naming exception is encountered 379 */ 380 public void rebind(String name, Object obj) throws NamingException; 381 382 /** 383 * Unbinds the named object. 384 * Removes the terminal atomic name in <code>name</code> 385 * from the target context--that named by all but the terminal 386 * atomic part of <code>name</code>. 387 * 388 * <p> This method is idempotent. 389 * It succeeds even if the terminal atomic name 390 * is not bound in the target context, but throws 391 * {@code NameNotFoundException} 392 * if any of the intermediate contexts do not exist. 393 * 394 * <p> Any attributes associated with the name are removed. 395 * Intermediate contexts are not changed. 396 * 397 * @param name 398 * the name to unbind; may not be empty 399 * @throws NameNotFoundException if an intermediate context does not exist 400 * @throws NamingException if a naming exception is encountered 401 * @see #unbind(String) 402 */ 403 public void unbind(Name name) throws NamingException; 404 405 /** 406 * Unbinds the named object. 407 * See {@link #unbind(Name)} for details. 408 * 409 * @param name 410 * the name to unbind; may not be empty 411 * @throws NameNotFoundException if an intermediate context does not exist 412 * @throws NamingException if a naming exception is encountered 413 */ 414 public void unbind(String name) throws NamingException; 415 416 /** 417 * Binds a new name to the object bound to an old name, and unbinds 418 * the old name. Both names are relative to this context. 419 * Any attributes associated with the old name become associated 420 * with the new name. 421 * Intermediate contexts of the old name are not changed. 422 * 423 * @param oldName 424 * the name of the existing binding; may not be empty 425 * @param newName 426 * the name of the new binding; may not be empty 427 * @throws NameAlreadyBoundException if {@code newName} is already bound 428 * @throws NamingException if a naming exception is encountered 429 * 430 * @see #rename(String, String) 431 * @see #bind(Name, Object) 432 * @see #rebind(Name, Object) 433 */ 434 public void rename(Name oldName, Name newName) throws NamingException; 435 436 /** 437 * Binds a new name to the object bound to an old name, and unbinds 438 * the old name. 439 * See {@link #rename(Name, Name)} for details. 440 * 441 * @param oldName 442 * the name of the existing binding; may not be empty 443 * @param newName 444 * the name of the new binding; may not be empty 445 * @throws NameAlreadyBoundException if {@code newName} is already bound 446 * @throws NamingException if a naming exception is encountered 447 */ 448 public void rename(String oldName, String newName) throws NamingException; 449 450 /** 451 * Enumerates the names bound in the named context, along with the 452 * class names of objects bound to them. 453 * The contents of any subcontexts are not included. 454 * 455 * <p> If a binding is added to or removed from this context, 456 * its effect on an enumeration previously returned is undefined. 457 * 458 * @param name 459 * the name of the context to list 460 * @return an enumeration of the names and class names of the 461 * bindings in this context. Each element of the 462 * enumeration is of type {@code NameClassPair}. 463 * @throws NamingException if a naming exception is encountered 464 * 465 * @see #list(String) 466 * @see #listBindings(Name) 467 * @see NameClassPair 468 */ 469 public NamingEnumeration<NameClassPair> list(Name name) 470 throws NamingException; 471 472 /** 473 * Enumerates the names bound in the named context, along with the 474 * class names of objects bound to them. 475 * See {@link #list(Name)} for details. 476 * 477 * @param name 478 * the name of the context to list 479 * @return an enumeration of the names and class names of the 480 * bindings in this context. Each element of the 481 * enumeration is of type {@code NameClassPair}. 482 * @throws NamingException if a naming exception is encountered 483 */ 484 public NamingEnumeration<NameClassPair> list(String name) 485 throws NamingException; 486 487 /** 488 * Enumerates the names bound in the named context, along with the 489 * objects bound to them. 490 * The contents of any subcontexts are not included. 491 * 492 * <p> If a binding is added to or removed from this context, 493 * its effect on an enumeration previously returned is undefined. 494 * 495 * @param name 496 * the name of the context to list 497 * @return an enumeration of the bindings in this context. 498 * Each element of the enumeration is of type 499 * {@code Binding}. 500 * @throws NamingException if a naming exception is encountered 501 * 502 * @see #listBindings(String) 503 * @see #list(Name) 504 * @see Binding 505 */ 506 public NamingEnumeration<Binding> listBindings(Name name) 507 throws NamingException; 508 509 /** 510 * Enumerates the names bound in the named context, along with the 511 * objects bound to them. 512 * See {@link #listBindings(Name)} for details. 513 * 514 * @param name 515 * the name of the context to list 516 * @return an enumeration of the bindings in this context. 517 * Each element of the enumeration is of type 518 * {@code Binding}. 519 * @throws NamingException if a naming exception is encountered 520 */ 521 public NamingEnumeration<Binding> listBindings(String name) 522 throws NamingException; 523 524 /** 525 * Destroys the named context and removes it from the namespace. 526 * Any attributes associated with the name are also removed. 527 * Intermediate contexts are not destroyed. 528 * 529 * <p> This method is idempotent. 530 * It succeeds even if the terminal atomic name 531 * is not bound in the target context, but throws 532 * {@code NameNotFoundException} 533 * if any of the intermediate contexts do not exist. 534 * 535 * <p> In a federated naming system, a context from one naming system 536 * may be bound to a name in another. One can subsequently 537 * look up and perform operations on the foreign context using a 538 * composite name. However, an attempt destroy the context using 539 * this composite name will fail with 540 * {@code NotContextException}, because the foreign context is not 541 * a "subcontext" of the context in which it is bound. 542 * Instead, use {@code unbind()} to remove the 543 * binding of the foreign context. Destroying the foreign context 544 * requires that the {@code destroySubcontext()} be performed 545 * on a context from the foreign context's "native" naming system. 546 * 547 * @param name 548 * the name of the context to be destroyed; may not be empty 549 * @throws NameNotFoundException if an intermediate context does not exist 550 * @throws NotContextException if the name is bound but does not name a 551 * context, or does not name a context of the appropriate type 552 * @throws ContextNotEmptyException if the named context is not empty 553 * @throws NamingException if a naming exception is encountered 554 * 555 * @see #destroySubcontext(String) 556 */ 557 public void destroySubcontext(Name name) throws NamingException; 558 559 /** 560 * Destroys the named context and removes it from the namespace. 561 * See {@link #destroySubcontext(Name)} for details. 562 * 563 * @param name 564 * the name of the context to be destroyed; may not be empty 565 * @throws NameNotFoundException if an intermediate context does not exist 566 * @throws NotContextException if the name is bound but does not name a 567 * context, or does not name a context of the appropriate type 568 * @throws ContextNotEmptyException if the named context is not empty 569 * @throws NamingException if a naming exception is encountered 570 */ 571 public void destroySubcontext(String name) throws NamingException; 572 573 /** 574 * Creates and binds a new context. 575 * Creates a new context with the given name and binds it in 576 * the target context (that named by all but terminal atomic 577 * component of the name). All intermediate contexts and the 578 * target context must already exist. 579 * 580 * @param name 581 * the name of the context to create; may not be empty 582 * @return the newly created context 583 * 584 * @throws NameAlreadyBoundException if name is already bound 585 * @throws javax.naming.directory.InvalidAttributesException 586 * if creation of the subcontext requires specification of 587 * mandatory attributes 588 * @throws NamingException if a naming exception is encountered 589 * 590 * @see #createSubcontext(String) 591 * @see javax.naming.directory.DirContext#createSubcontext 592 */ 593 public Context createSubcontext(Name name) throws NamingException; 594 595 /** 596 * Creates and binds a new context. 597 * See {@link #createSubcontext(Name)} for details. 598 * 599 * @param name 600 * the name of the context to create; may not be empty 601 * @return the newly created context 602 * 603 * @throws NameAlreadyBoundException if name is already bound 604 * @throws javax.naming.directory.InvalidAttributesException 605 * if creation of the subcontext requires specification of 606 * mandatory attributes 607 * @throws NamingException if a naming exception is encountered 608 */ 609 public Context createSubcontext(String name) throws NamingException; 610 611 /** 612 * Retrieves the named object, following links except 613 * for the terminal atomic component of the name. 614 * If the object bound to {@code name} is not a link, 615 * returns the object itself. 616 * 617 * @param name 618 * the name of the object to look up 619 * @return the object bound to {@code name}, not following the 620 * terminal link (if any). 621 * @throws NamingException if a naming exception is encountered 622 * 623 * @see #lookupLink(String) 624 */ 625 public Object lookupLink(Name name) throws NamingException; 626 627 /** 628 * Retrieves the named object, following links except 629 * for the terminal atomic component of the name. 630 * See {@link #lookupLink(Name)} for details. 631 * 632 * @param name 633 * the name of the object to look up 634 * @return the object bound to {@code name}, not following the 635 * terminal link (if any) 636 * @throws NamingException if a naming exception is encountered 637 */ 638 public Object lookupLink(String name) throws NamingException; 639 640 /** 641 * Retrieves the parser associated with the named context. 642 * In a federation of namespaces, different naming systems will 643 * parse names differently. This method allows an application 644 * to get a parser for parsing names into their atomic components 645 * using the naming convention of a particular naming system. 646 * Within any single naming system, {@code NameParser} objects 647 * returned by this method must be equal (using the {@code equals()} 648 * test). 649 * 650 * @param name 651 * the name of the context from which to get the parser 652 * @return a name parser that can parse compound names into their atomic 653 * components 654 * @throws NamingException if a naming exception is encountered 655 * 656 * @see #getNameParser(String) 657 * @see CompoundName 658 */ 659 public NameParser getNameParser(Name name) throws NamingException; 660 661 /** 662 * Retrieves the parser associated with the named context. 663 * See {@link #getNameParser(Name)} for details. 664 * 665 * @param name 666 * the name of the context from which to get the parser 667 * @return a name parser that can parse compound names into their atomic 668 * components 669 * @throws NamingException if a naming exception is encountered 670 */ 671 public NameParser getNameParser(String name) throws NamingException; 672 673 /** 674 * Composes the name of this context with a name relative to 675 * this context. 676 * Given a name (<code>name</code>) relative to this context, and 677 * the name (<code>prefix</code>) of this context relative to one 678 * of its ancestors, this method returns the composition of the 679 * two names using the syntax appropriate for the naming 680 * system(s) involved. That is, if <code>name</code> names an 681 * object relative to this context, the result is the name of the 682 * same object, but relative to the ancestor context. None of the 683 * names may be null. 684 * <p> 685 * For example, if this context is named "wiz.com" relative 686 * to the initial context, then 687 * <pre> 688 * composeName("east", "wiz.com") </pre> 689 * might return <code>"east.wiz.com"</code>. 690 * If instead this context is named "org/research", then 691 * <pre> 692 * composeName("user/jane", "org/research") </pre> 693 * might return <code>"org/research/user/jane"</code> while 694 * <pre> 695 * composeName("user/jane", "research") </pre> 696 * returns <code>"research/user/jane"</code>. 697 * 698 * @param name 699 * a name relative to this context 700 * @param prefix 701 * the name of this context relative to one of its ancestors 702 * @return the composition of <code>prefix</code> and <code>name</code> 703 * @throws NamingException if a naming exception is encountered 704 * 705 * @see #composeName(String, String) 706 */ 707 public Name composeName(Name name, Name prefix) 708 throws NamingException; 709 710 /** 711 * Composes the name of this context with a name relative to 712 * this context. 713 * See {@link #composeName(Name, Name)} for details. 714 * 715 * @param name 716 * a name relative to this context 717 * @param prefix 718 * the name of this context relative to one of its ancestors 719 * @return the composition of <code>prefix</code> and <code>name</code> 720 * @throws NamingException if a naming exception is encountered 721 */ 722 public String composeName(String name, String prefix) 723 throws NamingException; 724 725 /** 726 * Adds a new environment property to the environment of this 727 * context. If the property already exists, its value is overwritten. 728 * See class description for more details on environment properties. 729 * 730 * @param propName 731 * the name of the environment property to add; may not be null 732 * @param propVal 733 * the value of the property to add; may not be null 734 * @return the previous value of the property, or null if the property was 735 * not in the environment before 736 * @throws NamingException if a naming exception is encountered 737 * 738 * @see #getEnvironment() 739 * @see #removeFromEnvironment(String) 740 */ 741 public Object addToEnvironment(String propName, Object propVal) 742 throws NamingException; 743 744 /** 745 * Removes an environment property from the environment of this 746 * context. See class description for more details on environment 747 * properties. 748 * 749 * @param propName 750 * the name of the environment property to remove; may not be null 751 * @return the previous value of the property, or null if the property was 752 * not in the environment 753 * @throws NamingException if a naming exception is encountered 754 * 755 * @see #getEnvironment() 756 * @see #addToEnvironment(String, Object) 757 */ 758 public Object removeFromEnvironment(String propName) 759 throws NamingException; 760 761 /** 762 * Retrieves the environment in effect for this context. 763 * See class description for more details on environment properties. 764 * 765 * <p> The caller should not make any changes to the object returned: 766 * their effect on the context is undefined. 767 * The environment of this context may be changed using 768 * {@code addToEnvironment()} and {@code removeFromEnvironment()}. 769 * 770 * @return the environment of this context; never null 771 * @throws NamingException if a naming exception is encountered 772 * 773 * @see #addToEnvironment(String, Object) 774 * @see #removeFromEnvironment(String) 775 */ 776 public Hashtable<?,?> getEnvironment() throws NamingException; 777 778 /** 779 * Closes this context. 780 * This method releases this context's resources immediately, instead of 781 * waiting for them to be released automatically by the garbage collector. 782 * 783 * <p> This method is idempotent: invoking it on a context that has 784 * already been closed has no effect. Invoking any other method 785 * on a closed context is not allowed, and results in undefined behaviour. 786 * 787 * @throws NamingException if a naming exception is encountered 788 */ 789 public void close() throws NamingException; 790 791 /** 792 * Retrieves the full name of this context within its own namespace. 793 * 794 * <p> Many naming services have a notion of a "full name" for objects 795 * in their respective namespaces. For example, an LDAP entry has 796 * a distinguished name, and a DNS record has a fully qualified name. 797 * This method allows the client application to retrieve this name. 798 * The string returned by this method is not a JNDI composite name 799 * and should not be passed directly to context methods. 800 * In naming systems for which the notion of full name does not 801 * make sense, {@code OperationNotSupportedException} is thrown. 802 * 803 * @return this context's name in its own namespace; never null 804 * @throws OperationNotSupportedException if the naming system does 805 * not have the notion of a full name 806 * @throws NamingException if a naming exception is encountered 807 * 808 * @since 1.3 809 */ 810 public String getNameInNamespace() throws NamingException; 811 812 // public static final: JLS says recommended style is to omit these modifiers 813 // because they are the default 814 815 /** 816 * Constant that holds the name of the environment property 817 * for specifying the initial context factory to use. The value 818 * of the property should be the fully qualified class name 819 * of the factory class that will create an initial context. 820 * This property may be specified in the environment parameter 821 * passed to the initial context constructor, 822 * a system property, or an application resource file. 823 * If it is not specified in any of these sources, 824 * {@code NoInitialContextException} is thrown when an initial 825 * context is required to complete an operation. 826 * 827 * <p> The value of this constant is "java.naming.factory.initial". 828 * 829 * @see InitialContext 830 * @see javax.naming.directory.InitialDirContext 831 * @see javax.naming.spi.NamingManager#getInitialContext 832 * @see javax.naming.spi.InitialContextFactory 833 * @see NoInitialContextException 834 * @see #addToEnvironment(String, Object) 835 * @see #removeFromEnvironment(String) 836 */ 837 String INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial"; 838 839 /** 840 * Constant that holds the name of the environment property 841 * for specifying the list of object factories to use. The value 842 * of the property should be a colon-separated list of the fully 843 * qualified class names of factory classes that will create an object 844 * given information about the object. 845 * This property may be specified in the environment, a system property, 846 * or one or more resource files. 847 * 848 * <p> The value of this constant is "java.naming.factory.object". 849 * 850 * @see javax.naming.spi.NamingManager#getObjectInstance 851 * @see javax.naming.spi.ObjectFactory 852 * @see #addToEnvironment(String, Object) 853 * @see #removeFromEnvironment(String) 854 */ 855 String OBJECT_FACTORIES = "java.naming.factory.object"; 856 857 /** 858 * Constant that holds the name of the environment property 859 * for specifying the list of state factories to use. The value 860 * of the property should be a colon-separated list of the fully 861 * qualified class names of state factory classes that will be used 862 * to get an object's state given the object itself. 863 * This property may be specified in the environment, a system property, 864 * or one or more resource files. 865 * 866 * <p> The value of this constant is "java.naming.factory.state". 867 * 868 * @see javax.naming.spi.NamingManager#getStateToBind 869 * @see javax.naming.spi.StateFactory 870 * @see #addToEnvironment(String, Object) 871 * @see #removeFromEnvironment(String) 872 * @since 1.3 873 */ 874 String STATE_FACTORIES = "java.naming.factory.state"; 875 876 /** 877 * Constant that holds the name of the environment property 878 * for specifying the list of package prefixes to use when 879 * loading in URL context factories. The value 880 * of the property should be a colon-separated list of package 881 * prefixes for the class name of the factory class that will create 882 * a URL context factory. 883 * This property may be specified in the environment, a system property, 884 * or one or more resource files. 885 * The prefix {@code com.sun.jndi.url} is always appended to 886 * the possibly empty list of package prefixes. 887 * 888 * <p> The value of this constant is "java.naming.factory.url.pkgs". 889 * 890 * @see javax.naming.spi.NamingManager#getObjectInstance 891 * @see javax.naming.spi.NamingManager#getURLContext 892 * @see javax.naming.spi.ObjectFactory 893 * @see #addToEnvironment(String, Object) 894 * @see #removeFromEnvironment(String) 895 */ 896 String URL_PKG_PREFIXES = "java.naming.factory.url.pkgs"; 897 898 /** 899 * Constant that holds the name of the environment property 900 * for specifying configuration information for the service provider 901 * to use. The value of the property should contain a URL string 902 * (e.g. "ldap://somehost:389"). 903 * This property may be specified in the environment, a system property, 904 * or a resource file. 905 * If it is not specified in any of these sources, 906 * the default configuration is determined by the service provider. 907 * 908 * <p> The value of this constant is "java.naming.provider.url". 909 * 910 * @see #addToEnvironment(String, Object) 911 * @see #removeFromEnvironment(String) 912 */ 913 String PROVIDER_URL = "java.naming.provider.url"; 914 915 /** 916 * Constant that holds the name of the environment property 917 * for specifying the DNS host and domain names to use for the 918 * JNDI URL context (for example, "dns://somehost/wiz.com"). 919 * This property may be specified in the environment, a system property, 920 * or a resource file. 921 * If it is not specified in any of these sources 922 * and the program attempts to use a JNDI URL containing a DNS name, 923 * a {@code ConfigurationException} will be thrown. 924 * 925 * <p> The value of this constant is "java.naming.dns.url". 926 * 927 * @see #addToEnvironment(String, Object) 928 * @see #removeFromEnvironment(String) 929 */ 930 String DNS_URL = "java.naming.dns.url"; 931 932 /** 933 * Constant that holds the name of the environment property for 934 * specifying the authoritativeness of the service requested. 935 * If the value of the property is the string "true", it means 936 * that the access is to the most authoritative source (i.e. bypass 937 * any cache or replicas). If the value is anything else, 938 * the source need not be (but may be) authoritative. 939 * If unspecified, the value defaults to "false". 940 * 941 * <p> The value of this constant is "java.naming.authoritative". 942 * 943 * @see #addToEnvironment(String, Object) 944 * @see #removeFromEnvironment(String) 945 */ 946 String AUTHORITATIVE = "java.naming.authoritative"; 947 948 /** 949 * Constant that holds the name of the environment property for 950 * specifying the batch size to use when returning data via the 951 * service's protocol. This is a hint to the provider to return 952 * the results of operations in batches of the specified size, so 953 * the provider can optimize its performance and usage of resources. 954 * The value of the property is the string representation of an 955 * integer. 956 * If unspecified, the batch size is determined by the service 957 * provider. 958 * 959 * <p> The value of this constant is "java.naming.batchsize". 960 * 961 * @see #addToEnvironment(String, Object) 962 * @see #removeFromEnvironment(String) 963 */ 964 String BATCHSIZE = "java.naming.batchsize"; 965 966 /** 967 * Constant that holds the name of the environment property for 968 * specifying how referrals encountered by the service provider 969 * are to be processed. The value of the property is one of the 970 * following strings: 971 * <dl> 972 * <dt>"follow" 973 * <dd>follow referrals automatically 974 * <dt>"ignore" 975 * <dd>ignore referrals 976 * <dt>"throw" 977 * <dd>throw {@code ReferralException} when a referral is encountered. 978 * </dl> 979 * If this property is not specified, the default is 980 * determined by the provider. 981 * 982 * <p> The value of this constant is "java.naming.referral". 983 * 984 * @see #addToEnvironment(String, Object) 985 * @see #removeFromEnvironment(String) 986 */ 987 String REFERRAL = "java.naming.referral"; 988 989 /** 990 * Constant that holds the name of the environment property for 991 * specifying the security protocol to use. 992 * Its value is a string determined by the service provider 993 * (e.g. "ssl"). 994 * If this property is unspecified, 995 * the behaviour is determined by the service provider. 996 * 997 * <p> The value of this constant is "java.naming.security.protocol". 998 * 999 * @see #addToEnvironment(String, Object) 1000 * @see #removeFromEnvironment(String) 1001 */ 1002 String SECURITY_PROTOCOL = "java.naming.security.protocol"; 1003 1004 /** 1005 * Constant that holds the name of the environment property for 1006 * specifying the security level to use. 1007 * Its value is one of the following strings: 1008 * "none", "simple", "strong". 1009 * If this property is unspecified, 1010 * the behaviour is determined by the service provider. 1011 * 1012 * <p> The value of this constant is "java.naming.security.authentication". 1013 * 1014 * @see #addToEnvironment(String, Object) 1015 * @see #removeFromEnvironment(String) 1016 */ 1017 String SECURITY_AUTHENTICATION = "java.naming.security.authentication"; 1018 1019 /** 1020 * Constant that holds the name of the environment property for 1021 * specifying the identity of the principal for authenticating 1022 * the caller to the service. The format of the principal 1023 * depends on the authentication scheme. 1024 * If this property is unspecified, 1025 * the behaviour is determined by the service provider. 1026 * 1027 * <p> The value of this constant is "java.naming.security.principal". 1028 * 1029 * @see #addToEnvironment(String, Object) 1030 * @see #removeFromEnvironment(String) 1031 */ 1032 String SECURITY_PRINCIPAL = "java.naming.security.principal"; 1033 1034 /** 1035 * Constant that holds the name of the environment property for 1036 * specifying the credentials of the principal for authenticating 1037 * the caller to the service. The value of the property depends 1038 * on the authentication scheme. For example, it could be a hashed 1039 * password, clear-text password, key, certificate, and so on. 1040 * If this property is unspecified, 1041 * the behaviour is determined by the service provider. 1042 * 1043 * <p> The value of this constant is "java.naming.security.credentials". 1044 * 1045 * @see #addToEnvironment(String, Object) 1046 * @see #removeFromEnvironment(String) 1047 */ 1048 1049 String SECURITY_CREDENTIALS = "java.naming.security.credentials"; 1050 /** 1051 * Constant that holds the name of the environment property for 1052 * specifying the preferred language to use with the service. 1053 * The value of the property is a colon-separated list of language 1054 * tags as defined in RFC 1766. 1055 * If this property is unspecified, 1056 * the language preference is determined by the service provider. 1057 * 1058 * <p> The value of this constant is "java.naming.language". 1059 * 1060 * @see #addToEnvironment(String, Object) 1061 * @see #removeFromEnvironment(String) 1062 */ 1063 String LANGUAGE = "java.naming.language"; 1064 1065 /** 1066 * @deprecated An environment property with this name is ignored 1067 * while constructing an initial context. 1068 * This constant was originally used as a property name to specify an 1069 * {@code Applet} to retrieve parameters from, when creating an initial 1070 * context. Currently any applet properties that need to be passed to an 1071 * initial context should be copied into the environment hashtable: 1072 * <pre>{@code 1073 * Hashtable env = new Hashtable(); 1074 * env.put(Context.INITIAL_CONTEXT_FACTORY, 1075 * ((Applet) this).getParameter(Context.INITIAL_CONTEXT_FACTORY)); 1076 * env.put(Context.PROVIDER_URL, 1077 * ((Applet) this).getParameter(Context.PROVIDER_URL)); 1078 * // ... other properties ... 1079 * 1080 * Context ctx = new InitialContext(env); 1081 * }</pre> 1082 * 1083 * @since 1.3 1084 */ 1085 @Deprecated 1086 String APPLET = "java.naming.applet"; 1087 };