Context


1   /*
2    * @(#)Context.java 1.12 04/07/16
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.naming;
9   
10  import java.util.Hashtable  ;
11  
12  /**
13   * This interface represents a naming context, which
14   * consists of a set of name-to-object bindings.
15   * It contains methods for examining and updating these bindings.
16   * <p>
17   * <h4>Names</h4>
18   * Each name passed as an argument to a <tt>Context</tt> method is relative
19   * to that context.  The empty name is used to name the context itself.
20   * A name parameter may never be null.
21   * <p>
22   * Most of the methods have overloaded versions with one taking a
23   * <code>Name</code> parameter and one taking a <code>String</code>.
24   * These overloaded versions are equivalent in that if
25   * the <code>Name</code> and <code>String</code> parameters are just
26   * different representations of the same name, then the overloaded
27   * versions of the same methods behave the same.
28   * In the method descriptions below, only one version is fully documented.
29   * The second version instead has a link to the first:  the same
30   * documentation applies to both.
31   * <p>
32   * For systems that support federation, <tt>String</tt> name arguments to
33   * <tt>Context</tt> methods are composite names. Name arguments that are
34   * instances of <tt>CompositeName</tt> are treated as composite names,
35   * while <tt>Name</tt> arguments that are not instances of
36   * <tt>CompositeName</tt> are treated as compound names (which might be
37   * instances of <tt>CompoundName</tt> or other implementations of compound
38   * names). This allows the results of <tt>NameParser.parse()</tt> to be used as
39   * arguments to the <tt>Context</tt> methods.
40   * Prior to JNDI 1.2, all name arguments were treated as composite names.
41   *<p>
42   * Furthermore, for systems that support federation, all names returned
43   * in a <tt>NamingEnumeration</tt>
44   * from <tt>list()</tt> and <tt>listBindings()</tt> are composite names
45   * represented as strings.
46   * See <tt>CompositeName</tt> for the string syntax of names.
47   *<p>
48   * For systems that do not support federation, the name arguments (in
49   * either <tt>Name</tt> or <tt>String</tt> forms) and the names returned in
50   * <tt>NamingEnumeration</tt> may be names in their own namespace rather than
51   * names in a composite namespace, at the discretion of the service
52   * provider.
53   *<p>
54   *<h4>Exceptions</h4>
55   * All the methods in this interface can throw a <tt>NamingException</tt> or
56   * any of its subclasses. See <tt>NamingException</tt> and their subclasses
57   * for details on each exception.
58   *<p>
59   *<h4>Concurrent Access</h4>
60   * A Context instance is not guaranteed to be synchronized against
61   * concurrent access by multiple threads.  Threads that need to access
62   * a single Context instance concurrently should synchronize amongst
63   * themselves and provide the necessary locking.  Multiple threads
64   * each manipulating a different Context instance need not
65   * synchronize.  Note that the {@link #lookup(Name) <tt>lookup</tt>}
66   * method, when passed an empty name, will return a new Context instance
67   * representing the same naming context.
68   *<p>
69   * For purposes of concurrency control,
70   * a Context operation that returns a <tt>NamingEnumeration</tt> is
71   * not considered to have completed while the enumeration is still in
72   * use, or while any referrals generated by that operation are still
73   * being followed.
74   *
75   *<p>
76   *<h4>Parameters</h4>
77   * A <tt>Name</tt> parameter passed to any method of the
78   * <tt>Context</tt> interface or one of its subinterfaces
79   * will not be modified by the service provider.
80   * The service provider may keep a reference to it
81   * for the duration of the operation, including any enumeration of the
82   * method's results and the processing of any referrals generated.
83   * The caller should not modify the object during this time.
84   * A <tt>Name</tt> returned by any such method is owned by the caller.
85   * The caller may subsequently modify it; the service provider may not.
86   *
87   *<p>
88   *<h4>Environment Properties</h4>
89   *<p>
90   * JNDI applications need a way to communicate various preferences
91   * and properties that define the environment in which naming and
92   * directory services are accessed. For example, a context might
93   * require specification of security credentials in order to access
94   * the service. Another context might require that server configuration
95   * information be supplied. These are referred to as the <em>environment</em>
96   * of a context. The <tt>Context</tt> interface provides methods for
97   * retrieving and updating this environment.
98   *<p>
99   * The environment is inherited from the parent context as
100  * context methods proceed from one context to the next. Changes to
101  * the environment of one context do not directly affect those
102  * of other contexts.
103  *<p>
104  * It is implementation-dependent when environment properties are used
105  * and/or verified for validity.  For example, some of the
106  * security-related properties are used by service providers to "log in"
107  * to the directory.  This login process might occur at the time the
108  * context is created, or the first time a method is invoked on the
109  * context.  When, and whether this occurs at all, is
110  * implementation-dependent.  When environment properties are added or
111  * removed from the context, verifying the validity of the changes is again
112  * implementation-dependent. For example, verification of some properties
113  * might occur at the time the change is made, or at the time the next
114  * operation is performed on the context, or not at all.
115  *<p>
116  * Any object with a reference to a context may examine that context's
117  * environment.  Sensitive information such as clear-text
118  * passwords should not be stored there unless the implementation is
119  * known to protect it.
120  *
121  *<p>
122  *<a name=RESOURCEFILES></a>
123  *<h4>Resource Files</h4>
124  *<p>
125  * To simplify the task of setting up the environment
126  * required by a JNDI application,
127  * application components and service providers may be distributed
128  * along with <em>resource files.</em>
129  * A JNDI resource file is a file in the properties file format (see
130  * {@link java.util.Properties#load <tt>java.util.Properties</tt>}),
131  * containing a list of key/value pairs.
132  * The key is the name of the property (e.g. "java.naming.factory.object")
133  * and the value is a string in the format defined
134  * for that property.  Here is an example of a JNDI resource file:
135  *
136  * <blockquote><tt><pre>
137  * java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
138  * java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
139  * java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
140  * </pre></tt></blockquote>
141  *
142  * The JNDI class library reads the resource files and makes the property
143  * values freely available.  Thus JNDI resource files should be considered
144  * to be "world readable", and sensitive information such as clear-text
145  * passwords should not be stored there.
146  *<p>
147  * There are two kinds of JNDI resource files:
148  * <em>provider</em> and <em>application</em>.
149  *
150  * <h5>Provider Resource Files</h5>
151  *
152  * Each service provider has an optional resource that lists properties
153  * specific to that provider.  The name of this resource is:
154  * <blockquote>
155  * [<em>prefix</em>/]<tt>jndiprovider.properties</tt>
156  * </blockquote>
157  * where <em>prefix</em> is
158  * the package name of the provider's context implementation(s),
159  * with each period (".") converted to a slash ("/").
160  *
161  * For example, suppose a service provider defines a context
162  * implementation with class name <tt>com.sun.jndi.ldap.LdapCtx</tt>.
163  * The provider resource for this provider is named
164  * <tt>com/sun/jndi/ldap/jndiprovider.properties</tt>.  If the class is
165  * not in a package, the resource's name is simply
166  * <tt>jndiprovider.properties</tt>.
167  *
168  * <p>
169  * <a name=LISTPROPS></a>
170  * Certain methods in the JNDI class library make use of the standard
171  * JNDI properties that specify lists of JNDI factories:
172  * <ul>
173  * <li>java.naming.factory.object
174  * <li>java.naming.factory.state
175  * <li>java.naming.factory.control
176  * <li>java.naming.factory.url.pkgs
177  * </ul>
178  * The JNDI library will consult the provider resource file
179  * when determining the values of these properties.
180  * Properties other than these may be set in the provider
181  * resource file at the discretion of the service provider.
182  * The service provider's documentation should clearly state which
183  * properties are allowed; other properties in the file will be ignored.
184  *
185  * <h5>Application Resource Files</h5>
186  *
187  * When an application is deployed, it will generally have several
188  * codebase directories and JARs in its classpath.  Similarly, when an
189  * applet is deployed, it will have a codebase and archives specifying
190  * where to find the applet's classes.  JNDI locates (using
191  * {@link ClassLoader#getResources <tt>ClassLoader.getResources()</tt>})
192  * all <em>application resource files</em> named <tt>jndi.properties</tt>
193  * in the classpath.
194  * In addition, if the file <i>java.home</i><tt>/lib/jndi.properties</tt>
195  * exists and is readable,
196  * JNDI treats it as an additional application resource file.
197  * (<i>java.home</i> indicates the
198  * directory named by the <tt>java.home</tt> system property.)
199  * All of the properties contained in these files are placed
200  * into the environment of the initial context.  This environment
201  * is then inherited by other contexts.
202  *
203  * <p>
204  * For each property found in more than one application resource file,
205  * JNDI uses the first value found or, in a few cases where it makes
206  * sense to do so, it concatenates all of the values (details are given
207  * below).
208  * For example, if the "java.naming.factory.object" property is found in
209  * three <tt>jndi.properties</tt> resource files, the
210  * list of object factories is a concatenation of the property
211  * values from all three files.
212  * Using this scheme, each deployable component is responsible for
213  * listing the factories that it exports.  JNDI automatically
214  * collects and uses all of these export lists when searching for factory
215  * classes.
216  *
217  * <p>
218  * Application resource files are available beginning with the Java 2
219  * Platform, except that the file in
220  * <i>java.home</i><tt>/lib</tt> may be used on earlier Java platforms as well.
221  *
222  * <h5>Search Algorithm for Properties</h5>
223  *
224  * When JNDI constructs an initial context, the context's environment
225  * is initialized with properties defined in the environment parameter
226  * passed to the constructor, the system properties, the applet parameters,
227  * and the application resource files.  See
228  * <a HREF=InitialContext.html#ENVIRONMENT><tt>InitialContext</tt></a>
229  * for details.
230  * This initial environment is then inherited by other context instances.
231  *
232  * <p>
233  * When the JNDI class library needs to determine
234  * the value of a property, it does so by merging
235  * the values from the following two sources, in order:
236  * <ol>
237  * <li>The environment of the context being operated on.
238  * <li>The provider resource file (<tt>jndiprovider.properties</tt>)
239  * for the context being operated on.
240  * </ol>
241  * For each property found in both of these two sources,
242  * JNDI determines the property's value as follows.  If the property is
243  * one of the standard JNDI properties that specify a list of JNDI
244  * factories (listed <a HREF=#LISTPROPS>above</a>), the values are
245  * concatenated into a single colon-separated list.  For other
246  * properties, only the first value found is used.
247  *
248  * <p>
249  * When a service provider needs to determine the value of a property,
250  * it will generally take that value directly from the environment.
251  * A service provider may define provider-specific properties
252  * to be placed in its own provider resource file.  In that
253  * case it should merge values as described in the previous paragraph.
254  *
255  * <p>
256  * In this way, each service provider developer can specify a list of
257  * factories to use with that service provider. These can be modified by
258  * the application resources specified by the deployer of the application
259  * or applet, which in turn can be modified by the user.
260  *
261  * @author Rosanna Lee
262  * @author Scott Seligman
263  * @author R. Vasudevan
264  * @version 1.12 04/07/16
265  *
266  * @since 1.3
267  */
268 
269 public interface Context {
270 
271     /**
272      * Retrieves the named object.
273      * If <tt>name</tt> is empty, returns a new instance of this context
274      * (which represents the same naming context as this context, but its
275      * environment may be modified independently and it may be accessed
276      * concurrently).
277      *
278      * @param name
279      *      the name of the object to look up
280      * @return  the object bound to <tt>name</tt>
281      * @throws  NamingException if a naming exception is encountered
282      *
283      * @see #lookup(String)
284      * @see #lookupLink(Name)
285      */
286     public Object   lookup(Name   name) throws NamingException  ;
287 
288     /**
289      * Retrieves the named object.
290      * See {@link #lookup(Name)} for details.
291      * @param name
292      *      the name of the object to look up
293      * @return  the object bound to <tt>name</tt>
294      * @throws  NamingException if a naming exception is encountered
295      */
296     public Object   lookup(String   name) throws NamingException  ;
297 
298     /**
299      * Binds a name to an object.
300      * All intermediate contexts and the target context (that named by all
301      * but terminal atomic component of the name) must already exist.
302      *
303      * @param name
304      *      the name to bind; may not be empty
305      * @param obj
306      *      the object to bind; possibly null
307      * @throws  NameAlreadyBoundException if name is already bound
308      * @throws  javax.naming.directory.InvalidAttributesException
309      *      if object did not supply all mandatory attributes
310      * @throws  NamingException if a naming exception is encountered
311      *
312      * @see #bind(String, Object)
313      * @see #rebind(Name, Object)
314      * @see javax.naming.directory.DirContext#bind(Name, Object,
315      *      javax.naming.directory.Attributes)
316      */
317     public void bind(Name   name, Object   obj) throws NamingException  ;
318 
319     /**
320      * Binds a name to an object.
321      * See {@link #bind(Name, Object)} for details.
322      *
323      * @param name
324      *      the name to bind; may not be empty
325      * @param obj
326      *      the object to bind; possibly null
327      * @throws  NameAlreadyBoundException if name is already bound
328      * @throws  javax.naming.directory.InvalidAttributesException
329      *      if object did not supply all mandatory attributes
330      * @throws  NamingException if a naming exception is encountered
331      */
332     public void bind(String   name, Object   obj) throws NamingException  ;
333 
334     /**
335      * Binds a name to an object, overwriting any existing binding.
336      * All intermediate contexts and the target context (that named by all
337      * but terminal atomic component of the name) must already exist.
338      *
339      * <p> If the object is a <tt>DirContext</tt>, any existing attributes
340      * associated with the name are replaced with those of the object.
341      * Otherwise, any existing attributes associated with the name remain
342      * unchanged.
343      *
344      * @param name
345      *      the name to bind; may not be empty
346      * @param obj
347      *      the object to bind; possibly null
348      * @throws  javax.naming.directory.InvalidAttributesException
349      *      if object did not supply all mandatory attributes
350      * @throws  NamingException if a naming exception is encountered
351      *
352      * @see #rebind(String, Object)
353      * @see #bind(Name, Object)
354      * @see javax.naming.directory.DirContext#rebind(Name, Object,
355      *      javax.naming.directory.Attributes)
356      * @see javax.naming.directory.DirContext
357      */
358     public void rebind(Name   name, Object   obj) throws NamingException  ;
359 
360     /**
361      * Binds a name to an object, overwriting any existing binding.
362      * See {@link #rebind(Name, Object)} for details.
363      *
364      * @param name
365      *      the name to bind; may not be empty
366      * @param obj
367      *      the object to bind; possibly null
368      * @throws  javax.naming.directory.InvalidAttributesException
369      *      if object did not supply all mandatory attributes
370      * @throws  NamingException if a naming exception is encountered
371      */
372     public void rebind(String   name, Object   obj) throws NamingException  ;
373 
374     /**
375      * Unbinds the named object.
376      * Removes the terminal atomic name in <code>name</code>
377      * from the target context--that named by all but the terminal
378      * atomic part of <code>name</code>.
379      *
380      * <p> This method is idempotent.
381      * It succeeds even if the terminal atomic name
382      * is not bound in the target context, but throws
383      * <tt>NameNotFoundException</tt>
384      * if any of the intermediate contexts do not exist.
385      *
386      * <p> Any attributes associated with the name are removed.
387      * Intermediate contexts are not changed.
388      *
389      * @param name
390      *      the name to unbind; may not be empty
391      * @throws  NameNotFoundException if an intermediate context does not exist
392      * @throws  NamingException if a naming exception is encountered
393      * @see #unbind(String)
394      */
395     public void unbind(Name   name) throws NamingException  ;
396 
397     /**
398      * Unbinds the named object.
399      * See {@link #unbind(Name)} for details.
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      */
406     public void unbind(String   name) throws NamingException  ;
407 
408     /**
409      * Binds a new name to the object bound to an old name, and unbinds
410      * the old name.  Both names are relative to this context.
411      * Any attributes associated with the old name become associated
412      * with the new name.
413      * Intermediate contexts of the old name are not changed.
414      *
415      * @param oldName
416      *      the name of the existing binding; may not be empty
417      * @param newName
418      *      the name of the new binding; may not be empty
419      * @throws  NameAlreadyBoundException if <tt>newName</tt> is already bound
420      * @throws  NamingException if a naming exception is encountered
421      *
422      * @see #rename(String, String)
423      * @see #bind(Name, Object)
424      * @see #rebind(Name, Object)
425      */
426     public void rename(Name   oldName, Name   newName) throws NamingException  ;
427 
428     /**
429      * Binds a new name to the object bound to an old name, and unbinds
430      * the old name.
431      * See {@link #rename(Name, Name)} for details.
432      *
433      * @param oldName
434      *      the name of the existing binding; may not be empty
435      * @param newName
436      *      the name of the new binding; may not be empty
437      * @throws  NameAlreadyBoundException if <tt>newName</tt> is already bound
438      * @throws  NamingException if a naming exception is encountered
439      */
440     public void rename(String   oldName, String   newName) throws NamingException  ;
441 
442     /**
443      * Enumerates the names bound in the named context, along with the
444      * class names of objects bound to them.
445      * The contents of any subcontexts are not included.
446      *
447      * <p> If a binding is added to or removed from this context,
448      * its effect on an enumeration previously returned is undefined.
449      *
450      * @param name
451      *      the name of the context to list
452      * @return  an enumeration of the names and class names of the
453      *      bindings in this context.  Each element of the
454      *      enumeration is of type <tt>NameClassPair</tt>.
455      * @throws  NamingException if a naming exception is encountered
456      *
457      * @see #list(String)
458      * @see #listBindings(Name)
459      * @see NameClassPair
460      */
461     public NamingEnumeration  <NameClassPair  > list(Name   name)
462     throws NamingException  ;
463 
464     /**
465      * Enumerates the names bound in the named context, along with the
466      * class names of objects bound to them.
467      * See {@link #list(Name)} for details.
468      *
469      * @param name
470      *      the name of the context to list
471      * @return  an enumeration of the names and class names of the
472      *      bindings in this context.  Each element of the
473      *      enumeration is of type <tt>NameClassPair</tt>.
474      * @throws  NamingException if a naming exception is encountered
475      */
476     public NamingEnumeration  <NameClassPair  > list(String   name)
477     throws NamingException  ;
478 
479     /**
480      * Enumerates the names bound in the named context, along with the
481      * objects bound to them.
482      * The contents of any subcontexts are not included.
483      *
484      * <p> If a binding is added to or removed from this context,
485      * its effect on an enumeration previously returned is undefined.
486      *
487      * @param name
488      *      the name of the context to list
489      * @return  an enumeration of the bindings in this context.
490      *      Each element of the enumeration is of type
491      *      <tt>Binding</tt>.
492      * @throws  NamingException if a naming exception is encountered
493      *
494      * @see #listBindings(String)
495      * @see #list(Name)
496      * @see Binding
497       */
498     public NamingEnumeration  <Binding  > listBindings(Name   name)
499     throws NamingException  ;
500 
501     /**
502      * Enumerates the names bound in the named context, along with the
503      * objects bound to them.
504      * See {@link #listBindings(Name)} for details.
505      *
506      * @param name
507      *      the name of the context to list
508      * @return  an enumeration of the bindings in this context.
509      *      Each element of the enumeration is of type
510      *      <tt>Binding</tt>.
511      * @throws  NamingException if a naming exception is encountered
512      */
513     public NamingEnumeration  <Binding  > listBindings(String   name)
514     throws NamingException  ;
515 
516     /**
517      * Destroys the named context and removes it from the namespace.
518      * Any attributes associated with the name are also removed.
519      * Intermediate contexts are not destroyed.
520      *
521      * <p> This method is idempotent.
522      * It succeeds even if the terminal atomic name
523      * is not bound in the target context, but throws
524      * <tt>NameNotFoundException</tt>
525      * if any of the intermediate contexts do not exist.
526      *
527      * <p> In a federated naming system, a context from one naming system
528      * may be bound to a name in another.  One can subsequently
529      * look up and perform operations on the foreign context using a
530      * composite name.  However, an attempt destroy the context using
531      * this composite name will fail with
532      * <tt>NotContextException</tt>, because the foreign context is not
533      * a "subcontext" of the context in which it is bound.
534      * Instead, use <tt>unbind()</tt> to remove the
535      * binding of the foreign context.  Destroying the foreign context
536      * requires that the <tt>destroySubcontext()</tt> be performed
537      * on a context from the foreign context's "native" naming system.
538      *
539      * @param name
540      *      the name of the context to be destroyed; may not be empty
541      * @throws  NameNotFoundException if an intermediate context does not exist
542      * @throws  NotContextException if the name is bound but does not name a
543      *      context, or does not name a context of the appropriate type
544      * @throws  ContextNotEmptyException if the named context is not empty
545      * @throws  NamingException if a naming exception is encountered
546      *
547      * @see #destroySubcontext(String)
548      */
549     public void destroySubcontext(Name   name) throws NamingException  ;
550 
551     /**
552      * Destroys the named context and removes it from the namespace.
553      * See {@link #destroySubcontext(Name)} for details.
554      *
555      * @param name
556      *      the name of the context to be destroyed; may not be empty
557      * @throws  NameNotFoundException if an intermediate context does not exist
558      * @throws  NotContextException if the name is bound but does not name a
559      *      context, or does not name a context of the appropriate type
560      * @throws  ContextNotEmptyException if the named context is not empty
561      * @throws  NamingException if a naming exception is encountered
562      */
563     public void destroySubcontext(String   name) throws NamingException  ;
564 
565     /**
566      * Creates and binds a new context.
567      * Creates a new context with the given name and binds it in
568      * the target context (that named by all but terminal atomic
569      * component of the name).  All intermediate contexts and the
570      * target context must already exist.
571      *
572      * @param name
573      *      the name of the context to create; may not be empty
574      * @return  the newly created context
575      *
576      * @throws  NameAlreadyBoundException if name is already bound
577      * @throws  javax.naming.directory.InvalidAttributesException
578      *      if creation of the subcontext requires specification of
579      *      mandatory attributes
580      * @throws  NamingException if a naming exception is encountered
581      *
582      * @see #createSubcontext(String)
583      * @see javax.naming.directory.DirContext#createSubcontext
584      */
585     public Context   createSubcontext(Name   name) throws NamingException  ;
586 
587     /**
588      * Creates and binds a new context.
589      * See {@link #createSubcontext(Name)} for details.
590      *
591      * @param name
592      *      the name of the context to create; may not be empty
593      * @return  the newly created context
594      *
595      * @throws  NameAlreadyBoundException if name is already bound
596      * @throws  javax.naming.directory.InvalidAttributesException
597      *      if creation of the subcontext requires specification of
598      *      mandatory attributes
599      * @throws  NamingException if a naming exception is encountered
600      */
601     public Context   createSubcontext(String   name) throws NamingException  ;
602 
603     /**
604      * Retrieves the named object, following links except
605      * for the terminal atomic component of the name.
606      * If the object bound to <tt>name</tt> is not a link,
607      * returns the object itself.
608      *
609      * @param name
610      *      the name of the object to look up
611      * @return  the object bound to <tt>name</tt>, not following the
612      *      terminal link (if any).
613      * @throws  NamingException if a naming exception is encountered
614      *
615      * @see #lookupLink(String)
616      */
617     public Object   lookupLink(Name   name) throws NamingException  ;
618 
619     /**
620      * Retrieves the named object, following links except
621      * for the terminal atomic component of the name.
622      * See {@link #lookupLink(Name)} for details.
623      *
624      * @param name
625      *      the name of the object to look up
626      * @return  the object bound to <tt>name</tt>, not following the
627      *      terminal link (if any)
628      * @throws  NamingException if a naming exception is encountered
629      */
630     public Object   lookupLink(String   name) throws NamingException  ;
631 
632     /**
633      * Retrieves the parser associated with the named context.
634      * In a federation of namespaces, different naming systems will
635      * parse names differently.  This method allows an application
636      * to get a parser for parsing names into their atomic components
637      * using the naming convention of a particular naming system.
638      * Within any single naming system, <tt>NameParser</tt> objects
639      * returned by this method must be equal (using the <tt>equals()</tt>
640      * test).
641      *
642      * @param name
643      *      the name of the context from which to get the parser
644      * @return  a name parser that can parse compound names into their atomic
645      *      components
646      * @throws  NamingException if a naming exception is encountered
647      *
648      * @see #getNameParser(String)
649      * @see CompoundName
650      */
651     public NameParser   getNameParser(Name   name) throws NamingException  ;
652 
653     /**
654      * Retrieves the parser associated with the named context.
655      * See {@link #getNameParser(Name)} for details.
656      *
657      * @param name
658      *      the name of the context from which to get the parser
659      * @return  a name parser that can parse compound names into their atomic
660      *      components
661      * @throws  NamingException if a naming exception is encountered
662      */
663     public NameParser   getNameParser(String   name) throws NamingException  ;
664 
665     /**
666      * Composes the name of this context with a name relative to
667      * this context.
668      * Given a name (<code>name</code>) relative to this context, and
669      * the name (<code>prefix</code>) of this context relative to one
670      * of its ancestors, this method returns the composition of the
671      * two names using the syntax appropriate for the naming
672      * system(s) involved.  That is, if <code>name</code> names an
673      * object relative to this context, the result is the name of the
674      * same object, but relative to the ancestor context.  None of the
675      * names may be null.
676      * <p>
677      * For example, if this context is named "wiz.com" relative
678      * to the initial context, then
679      * <pre>
680      *  composeName("east", "wiz.com")  </pre>
681      * might return <code>"east.wiz.com"</code>.
682      * If instead this context is named "org/research", then
683      * <pre>
684      *  composeName("user/jane", "org/research")    </pre>
685      * might return <code>"org/research/user/jane"</code> while
686      * <pre>
687      *  composeName("user/jane", "research")    </pre>
688      * returns <code>"research/user/jane"</code>.
689      *
690      * @param name
691      *      a name relative to this context
692      * @param prefix
693      *      the name of this context relative to one of its ancestors
694      * @return  the composition of <code>prefix</code> and <code>name</code>
695      * @throws  NamingException if a naming exception is encountered
696      *
697      * @see #composeName(String, String)
698      */
699     public Name   composeName(Name   name, Name   prefix)
700     throws NamingException  ;
701 
702     /**
703      * Composes the name of this context with a name relative to
704      * this context.
705      * See {@link #composeName(Name, Name)} for details.
706      *
707      * @param name
708      *      a name relative to this context
709      * @param prefix
710      *      the name of this context relative to one of its ancestors
711      * @return  the composition of <code>prefix</code> and <code>name</code>
712      * @throws  NamingException if a naming exception is encountered
713      */
714     public String   composeName(String   name, String   prefix)
715         throws NamingException  ;
716 
717     /**
718      * Adds a new environment property to the environment of this
719      * context.  If the property already exists, its value is overwritten.
720      * See class description for more details on environment properties.
721      *
722      * @param propName
723      *      the name of the environment property to add; may not be null
724      * @param propVal
725      *      the value of the property to add; may not be null
726      * @return  the previous value of the property, or null if the property was
727      *      not in the environment before
728      * @throws  NamingException if a naming exception is encountered
729      *
730      * @see #getEnvironment()
731      * @see #removeFromEnvironment(String)
732      */
733     public Object   addToEnvironment(String   propName, Object   propVal)
734     throws NamingException  ;
735 
736     /**
737      * Removes an environment property from the environment of this
738      * context.  See class description for more details on environment
739      * properties.
740      *
741      * @param propName
742      *      the name of the environment property to remove; may not be null
743      * @return  the previous value of the property, or null if the property was
744      *      not in the environment
745      * @throws  NamingException if a naming exception is encountered
746      *
747      * @see #getEnvironment()
748      * @see #addToEnvironment(String, Object)
749      */
750     public Object   removeFromEnvironment(String   propName)
751     throws NamingException  ;
752 
753     /**
754      * Retrieves the environment in effect for this context.
755      * See class description for more details on environment properties.
756      *
757      * <p> The caller should not make any changes to the object returned:
758      * their effect on the context is undefined.
759      * The environment of this context may be changed using
760      * <tt>addToEnvironment()</tt> and <tt>removeFromEnvironment()</tt>.
761      *
762      * @return  the environment of this context; never null
763      * @throws  NamingException if a naming exception is encountered
764      *
765      * @see #addToEnvironment(String, Object)
766      * @see #removeFromEnvironment(String)
767      */
768     public Hashtable  <?,?> getEnvironment() throws NamingException  ;
769 
770     /**
771      * Closes this context.
772      * This method releases this context's resources immediately, instead of
773      * waiting for them to be released automatically by the garbage collector.
774      *
775      * <p> This method is idempotent:  invoking it on a context that has
776      * already been closed has no effect.  Invoking any other method
777      * on a closed context is not allowed, and results in undefined behaviour.
778      *
779      * @throws  NamingException if a naming exception is encountered
780      */
781     public void close() throws NamingException  ;
782 
783     /**
784      * Retrieves the full name of this context within its own namespace.
785      *
786      * <p> Many naming services have a notion of a "full name" for objects
787      * in their respective namespaces.  For example, an LDAP entry has
788      * a distinguished name, and a DNS record has a fully qualified name.
789      * This method allows the client application to retrieve this name.
790      * The string returned by this method is not a JNDI composite name
791      * and should not be passed directly to context methods.
792      * In naming systems for which the notion of full name does not
793      * make sense, <tt>OperationNotSupportedException</tt> is thrown.
794      *
795      * @return  this context's name in its own namespace; never null
796      * @throws  OperationNotSupportedException if the naming system does
797      *      not have the notion of a full name
798      * @throws  NamingException if a naming exception is encountered
799      *
800      * @since 1.3
801      */
802     public String   getNameInNamespace() throws NamingException  ;
803 
804 // public static final:  JLS says recommended style is to omit these modifiers
805 // because they are the default
806 
807     /**
808      * Constant that holds the name of the environment property
809      * for specifying the initial context factory to use. The value
810      * of the property should be the fully qualified class name
811      * of the factory class that will create an initial context.
812      * This property may be specified in the environment parameter
813      * passed to the initial context constructor, an applet parameter,
814      * a system property, or an application resource file.
815      * If it is not specified in any of these sources,
816      * <tt>NoInitialContextException</tt> is thrown when an initial
817      * context is required to complete an operation.
818      *
819      * <p> The value of this constant is "java.naming.factory.initial".
820      *
821      * @see InitialContext
822      * @see javax.naming.directory.InitialDirContext
823      * @see javax.naming.spi.NamingManager#getInitialContext
824      * @see javax.naming.spi.InitialContextFactory
825      * @see NoInitialContextException
826      * @see #addToEnvironment(String, Object)
827      * @see #removeFromEnvironment(String)
828      * @see #APPLET
829      */
830     String   INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial";
831 
832     /**
833      * Constant that holds the name of the environment property
834      * for specifying the list of object factories to use. The value
835      * of the property should be a colon-separated list of the fully
836      * qualified class names of factory classes that will create an object
837      * given information about the object.
838      * This property may be specified in the environment, an applet
839      * parameter, a system property, or one or more resource files.
840      *
841      * <p> The value of this constant is "java.naming.factory.object".
842      *
843      * @see javax.naming.spi.NamingManager#getObjectInstance
844      * @see javax.naming.spi.ObjectFactory
845      * @see #addToEnvironment(String, Object)
846      * @see #removeFromEnvironment(String)
847      * @see #APPLET
848      */
849     String   OBJECT_FACTORIES = "java.naming.factory.object";
850 
851     /**
852      * Constant that holds the name of the environment property
853      * for specifying the list of state factories to use. The value
854      * of the property should be a colon-separated list of the fully
855      * qualified class names of state factory classes that will be used
856      * to get an object's state given the object itself.
857      * This property may be specified in the environment, an applet
858      * parameter, a system property, or one or more resource files.
859      *
860      * <p> The value of this constant is "java.naming.factory.state".
861      *
862      * @see javax.naming.spi.NamingManager#getStateToBind
863      * @see javax.naming.spi.StateFactory
864      * @see #addToEnvironment(String, Object)
865      * @see #removeFromEnvironment(String)
866      * @see #APPLET
867      * @since 1.3
868      */
869     String   STATE_FACTORIES = "java.naming.factory.state";
870 
871     /**
872      * Constant that holds the name of the environment property
873      * for specifying the list of package prefixes to use when
874      * loading in URL context factories. The value
875      * of the property should be a colon-separated list of package
876      * prefixes for the class name of the factory class that will create
877      * a URL context factory.
878      * This property may be specified in the environment,
879      * an applet parameter, a system property, or one or more
880      * resource files.
881      * The prefix <tt>com.sun.jndi.url</tt> is always appended to
882      * the possibly empty list of package prefixes.
883      *
884      * <p> The value of this constant is "java.naming.factory.url.pkgs".
885      *
886      * @see javax.naming.spi.NamingManager#getObjectInstance
887      * @see javax.naming.spi.NamingManager#getURLContext
888      * @see javax.naming.spi.ObjectFactory
889      * @see #addToEnvironment(String, Object)
890      * @see #removeFromEnvironment(String)
891      * @see #APPLET
892       */
893     String   URL_PKG_PREFIXES = "java.naming.factory.url.pkgs";
894 
895     /**
896      * Constant that holds the name of the environment property
897      * for specifying configuration information for the service provider
898      * to use. The value of the property should contain a URL string
899      * (e.g. "ldap://somehost:389").
900      * This property may be specified in the environment,
901      * an applet parameter, a system property, or a resource file.
902      * If it is not specified in any of these sources,
903      * the default configuration is determined by the service provider.
904      *
905      * <p> The value of this constant is "java.naming.provider.url".
906      *
907      * @see #addToEnvironment(String, Object)
908      * @see #removeFromEnvironment(String)
909      * @see #APPLET
910      */
911     String   PROVIDER_URL = "java.naming.provider.url";
912 
913     /**
914      * Constant that holds the name of the environment property
915      * for specifying the DNS host and domain names to use for the
916      * JNDI URL context (for example, "dns://somehost/wiz.com").
917      * This property may be specified in the environment,
918      * an applet parameter, a system property, or a resource file.
919      * If it is not specified in any of these sources
920      * and the program attempts to use a JNDI URL containing a DNS name,
921      * a <tt>ConfigurationException</tt> will be thrown.
922      *
923      * <p> The value of this constant is "java.naming.dns.url".
924      *
925      * @see #addToEnvironment(String, Object)
926      * @see #removeFromEnvironment(String)
927      */
928     String   DNS_URL = "java.naming.dns.url";
929 
930     /**
931      * Constant that holds the name of the environment property for
932      * specifying the authoritativeness of the service requested.
933      * If the value of the property is the string "true", it means
934      * that the access is to the most authoritative source (i.e. bypass
935      * any cache or replicas). If the value is anything else,
936      * the source need not be (but may be) authoritative.
937      * If unspecified, the value defaults to "false".
938      *
939      * <p> The value of this constant is "java.naming.authoritative".
940      *
941      * @see #addToEnvironment(String, Object)
942      * @see #removeFromEnvironment(String)
943      */
944     String   AUTHORITATIVE = "java.naming.authoritative";
945 
946     /**
947      * Constant that holds the name of the environment property for
948      * specifying the batch size to use when returning data via the
949      * service's protocol. This is a hint to the provider to return
950      * the results of operations in batches of the specified size, so
951      * the provider can optimize its performance and usage of resources.
952      * The value of the property is the string representation of an
953      * integer.
954      * If unspecified, the batch size is determined by the service
955      * provider.
956      *
957      * <p> The value of this constant is "java.naming.batchsize".
958      *
959      * @see #addToEnvironment(String, Object)
960      * @see #removeFromEnvironment(String)
961      */
962     String   BATCHSIZE = "java.naming.batchsize";
963 
964     /**
965      * Constant that holds the name of the environment property for
966      * specifying how referrals encountered by the service provider
967      * are to be processed. The value of the property is one of the
968      * following strings:
969      * <dl>
970      * <dt>"follow"
971      * <dd>follow referrals automatically
972      * <dt>"ignore"
973      * <dd>ignore referrals
974      * <dt>"throw"
975      * <dd>throw <tt>ReferralException</tt> when a referral is encountered.
976      * </dl>
977      * If this property is not specified, the default is
978      * determined by the provider.
979      *
980      * <p> The value of this constant is "java.naming.referral".
981      *
982      * @see #addToEnvironment(String, Object)
983      * @see #removeFromEnvironment(String)
984      */
985     String   REFERRAL = "java.naming.referral";
986 
987     /**
988      * Constant that holds the name of the environment property for
989      * specifying the security protocol to use.
990      * Its value is a string determined by the service provider
991      * (e.g. "ssl").
992      * If this property is unspecified,
993      * the behaviour is determined by the service provider.
994      *
995      * <p> The value of this constant is "java.naming.security.protocol".
996      *
997      * @see #addToEnvironment(String, Object)
998      * @see #removeFromEnvironment(String)
999      */
1000    String   SECURITY_PROTOCOL = "java.naming.security.protocol";
1001
1002    /**
1003     * Constant that holds the name of the environment property for
1004     * specifying the security level to use.
1005     * Its value is one of the following strings:
1006     * "none", "simple", "strong".
1007     * If this property is unspecified,
1008     * the behaviour is determined by the service provider.
1009     *
1010     * <p> The value of this constant is "java.naming.security.authentication".
1011     *
1012     * @see #addToEnvironment(String, Object)
1013     * @see #removeFromEnvironment(String)
1014     */
1015    String   SECURITY_AUTHENTICATION = "java.naming.security.authentication";
1016
1017    /**
1018     * Constant that holds the name of the environment property for
1019     * specifying the identity of the principal for authenticating
1020     * the caller to the service. The format of the principal
1021     * depends on the authentication scheme.
1022     * If this property is unspecified,
1023     * the behaviour is determined by the service provider.
1024     *
1025     * <p> The value of this constant is "java.naming.security.principal".
1026     *
1027     * @see #addToEnvironment(String, Object)
1028     * @see #removeFromEnvironment(String)
1029     */
1030    String   SECURITY_PRINCIPAL = "java.naming.security.principal";
1031
1032    /**
1033     * Constant that holds the name of the environment property for
1034     * specifying the credentials of the principal for authenticating
1035     * the caller to the service. The value of the property depends
1036     * on the authentication scheme. For example, it could be a hashed
1037     * password, clear-text password, key, certificate, and so on.
1038     * If this property is unspecified,
1039     * the behaviour is determined by the service provider.
1040     *
1041     * <p> The value of this constant is "java.naming.security.credentials".
1042     *
1043     * @see #addToEnvironment(String, Object)
1044     * @see #removeFromEnvironment(String)
1045     */
1046
1047    String   SECURITY_CREDENTIALS = "java.naming.security.credentials";
1048    /**
1049     * Constant that holds the name of the environment property for
1050     * specifying the preferred language to use with the service.
1051     * The value of the property is a colon-separated list of language
1052     * tags as defined in RFC 1766.
1053     * If this property is unspecified,
1054     * the language preference is determined by the service provider.
1055     *
1056     * <p> The value of this constant is "java.naming.language".
1057     *
1058     * @see #addToEnvironment(String, Object)
1059     * @see #removeFromEnvironment(String)
1060     */
1061    String   LANGUAGE = "java.naming.language";
1062
1063    /**
1064     * Constant that holds the name of the environment property for
1065     * specifying an applet for the initial context constructor to use
1066     * when searching for other properties.
1067     * The value of this property is the
1068     * <tt>java.applet.Applet</tt> instance that is being executed.
1069     * This property may be specified in the environment parameter
1070     * passed to the initial context constructor.
1071     * When this property is set, each property that the initial context
1072     * constructor looks for in the system properties is first looked for
1073     * in the applet's parameter list.
1074     * If this property is unspecified, the initial context constructor
1075     * will search for properties only in the environment parameter
1076     * passed to it, the system properties, and application resource files.
1077     *
1078     * <p> The value of this constant is "java.naming.applet".
1079     *
1080     * @see #addToEnvironment(String, Object)
1081     * @see #removeFromEnvironment(String)
1082     * @see InitialContext
1083     *
1084     * @since 1.3
1085     */
1086    String   APPLET = "java.naming.applet";
1087};
1088
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags