1 /*
2 * Copyright (c) 1999, 2017, 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 id=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 id=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 };