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