View Javadoc
1   /*
2    * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.naming;
27  
28  import java.util.Hashtable;
29  
30  /**
31   * This interface represents a naming context, which
32   * consists of a set of name-to-object bindings.
33   * It contains methods for examining and updating these bindings.
34   *
35   * <h1>Names</h1>
36   * Each name passed as an argument to a <tt>Context</tt> method is relative
37   * to that context.  The empty name is used to name the context itself.
38   * A name parameter may never be null.
39   * <p>
40   * Most of the methods have overloaded versions with one taking a
41   * <code>Name</code> parameter and one taking a <code>String</code>.
42   * These overloaded versions are equivalent in that if
43   * the <code>Name</code> and <code>String</code> parameters are just
44   * different representations of the same name, then the overloaded
45   * versions of the same methods behave the same.
46   * In the method descriptions below, only one version is fully documented.
47   * The second version instead has a link to the first:  the same
48   * documentation applies to both.
49   * <p>
50   * For systems that support federation, <tt>String</tt> name arguments to
51   * <tt>Context</tt> methods are composite names. Name arguments that are
52   * instances of <tt>CompositeName</tt> are treated as composite names,
53   * while <tt>Name</tt> arguments that are not instances of
54   * <tt>CompositeName</tt> are treated as compound names (which might be
55   * instances of <tt>CompoundName</tt> or other implementations of compound
56   * names). This allows the results of <tt>NameParser.parse()</tt> to be used as
57   * arguments to the <tt>Context</tt> methods.
58   * Prior to JNDI 1.2, all name arguments were treated as composite names.
59   *<p>
60   * Furthermore, for systems that support federation, all names returned
61   * in a <tt>NamingEnumeration</tt>
62   * from <tt>list()</tt> and <tt>listBindings()</tt> are composite names
63   * represented as strings.
64   * See <tt>CompositeName</tt> for the string syntax of names.
65   *<p>
66   * For systems that do not support federation, the name arguments (in
67   * either <tt>Name</tt> or <tt>String</tt> forms) and the names returned in
68   * <tt>NamingEnumeration</tt> may be names in their own namespace rather than
69   * names in a composite namespace, at the discretion of the service
70   * provider.
71   *
72   *<h1>Exceptions</h1>
73   * All the methods in this interface can throw a <tt>NamingException</tt> or
74   * any of its subclasses. See <tt>NamingException</tt> and their subclasses
75   * for details on each exception.
76   *
77   *<h1>Concurrent Access</h1>
78   * A Context instance is not guaranteed to be synchronized against
79   * concurrent access by multiple threads.  Threads that need to access
80   * a single Context instance concurrently should synchronize amongst
81   * themselves and provide the necessary locking.  Multiple threads
82   * each manipulating a different Context instance need not
83   * synchronize.  Note that the {@link #lookup(Name) <tt>lookup</tt>}
84   * method, when passed an empty name, will return a new Context instance
85   * representing the same naming context.
86   *<p>
87   * For purposes of concurrency control,
88   * a Context operation that returns a <tt>NamingEnumeration</tt> is
89   * not considered to have completed while the enumeration is still in
90   * use, or while any referrals generated by that operation are still
91   * being followed.
92   *
93   *
94   *<h1>Parameters</h1>
95   * A <tt>Name</tt> parameter passed to any method of the
96   * <tt>Context</tt> interface or one of its subinterfaces
97   * will not be modified by the service provider.
98   * The service provider may keep a reference to it
99   * for the duration of the operation, including any enumeration of the
100  * method's results and the processing of any referrals generated.
101  * The caller should not modify the object during this time.
102  * A <tt>Name</tt> returned by any such method is owned by the caller.
103  * The caller may subsequently modify it; the service provider may not.
104  *
105  *
106  *<h1>Environment Properties</h1>
107  *<p>
108  * JNDI applications need a way to communicate various preferences
109  * and properties that define the environment in which naming and
110  * directory services are accessed. For example, a context might
111  * require specification of security credentials in order to access
112  * the service. Another context might require that server configuration
113  * information be supplied. These are referred to as the <em>environment</em>
114  * of a context. The <tt>Context</tt> interface provides methods for
115  * retrieving and updating this environment.
116  *<p>
117  * The environment is inherited from the parent context as
118  * context methods proceed from one context to the next. Changes to
119  * the environment of one context do not directly affect those
120  * of other contexts.
121  *<p>
122  * It is implementation-dependent when environment properties are used
123  * and/or verified for validity.  For example, some of the
124  * security-related properties are used by service providers to "log in"
125  * to the directory.  This login process might occur at the time the
126  * context is created, or the first time a method is invoked on the
127  * context.  When, and whether this occurs at all, is
128  * implementation-dependent.  When environment properties are added or
129  * removed from the context, verifying the validity of the changes is again
130  * implementation-dependent. For example, verification of some properties
131  * might occur at the time the change is made, or at the time the next
132  * operation is performed on the context, or not at all.
133  *<p>
134  * Any object with a reference to a context may examine that context's
135  * environment.  Sensitive information such as clear-text
136  * passwords should not be stored there unless the implementation is
137  * known to protect it.
138  *
139  *<p>
140  *<a name=RESOURCEFILES></a>
141  *<h1>Resource Files</h1>
142  *<p>
143  * To simplify the task of setting up the environment
144  * required by a JNDI application,
145  * application components and service providers may be distributed
146  * along with <em>resource files.</em>
147  * A JNDI resource file is a file in the properties file format (see
148  * {@link java.util.Properties#load <tt>java.util.Properties</tt>}),
149  * containing a list of key/value pairs.
150  * The key is the name of the property (e.g. "java.naming.factory.object")
151  * and the value is a string in the format defined
152  * for that property.  Here is an example of a JNDI resource file:
153  *
154  * <blockquote>{@code
155  * java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
156  * java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
157  * java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
158  * }</blockquote>
159  *
160  * The JNDI class library reads the resource files and makes the property
161  * values freely available.  Thus JNDI resource files should be considered
162  * to be "world readable", and sensitive information such as clear-text
163  * passwords should not be stored there.
164  *<p>
165  * There are two kinds of JNDI resource files:
166  * <em>provider</em> and <em>application</em>.
167  *
168  * <h2>Provider Resource Files</h2>
169  *
170  * Each service provider has an optional resource that lists properties
171  * specific to that provider.  The name of this resource is:
172  * <blockquote>
173  * [<em>prefix</em>/]<tt>jndiprovider.properties</tt>
174  * </blockquote>
175  * where <em>prefix</em> is
176  * the package name of the provider's context implementation(s),
177  * with each period (".") converted to a slash ("/").
178  *
179  * For example, suppose a service provider defines a context
180  * implementation with class name <tt>com.sun.jndi.ldap.LdapCtx</tt>.
181  * The provider resource for this provider is named
182  * <tt>com/sun/jndi/ldap/jndiprovider.properties</tt>.  If the class is
183  * not in a package, the resource's name is simply
184  * <tt>jndiprovider.properties</tt>.
185  *
186  * <p>
187  * <a name=LISTPROPS></a>
188  * Certain methods in the JNDI class library make use of the standard
189  * JNDI properties that specify lists of JNDI factories:
190  * <ul>
191  * <li>java.naming.factory.object
192  * <li>java.naming.factory.state
193  * <li>java.naming.factory.control
194  * <li>java.naming.factory.url.pkgs
195  * </ul>
196  * The JNDI library will consult the provider resource file
197  * when determining the values of these properties.
198  * Properties other than these may be set in the provider
199  * resource file at the discretion of the service provider.
200  * The service provider's documentation should clearly state which
201  * properties are allowed; other properties in the file will be ignored.
202  *
203  * <h2>Application Resource Files</h2>
204  *
205  * When an application is deployed, it will generally have several
206  * codebase directories and JARs in its classpath.  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  * <h2>Search Algorithm for Properties</h2>
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 };