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