001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.naming;
019:
020: import java.util.Hashtable;
021:
022: /**
023: * The <code>Context</code> interface describes a naming context comprising a
024: * collection of bindings (see <code>javax.naming.Binding</code>) and methods
025: * for manipulating them. This interface is extended by interfaces
026: * <code>javax.naming.directory.DirContext</code> and
027: * <code>javax.naming.event.EventContext</code>. The class
028: * <code>javax.naming.InitialContext</code> implements the
029: * <code>Context</code> interface.
030: * <p>
031: * Any of the methods may throw a <code>NamingException</code> or one of its
032: * subclasses. The specifications for those exceptions explain the circumstances
033: * in which they may be thrown.
034: * </p>
035: * <p>
036: * Name parameters to context methods are each relative to the context. Name
037: * parameters cannot be null. The empty name, whether of type <code>Name</code>
038: * or <code>String</code>, is the name of the initial context. Names may be
039: * composed of multiple components; for example, in the filesystem name
040: * "usr/include/stdio.h", each of the components "usr", "include", "stdio.h" is
041: * an atomic component, but only "stdio.h" is the terminal atomic component. The
042: * example name may be used in context operations providing the intervening
043: * parent contexts for "usr" and "include" already exist. Finally, if the
044: * current context has name "usr/include", then the example name could be the
045: * result of <code>composeName("stdio.h","usr/include")</code>.
046: * </p>
047: * <p>
048: * Depending on whether a naming system supports federation, that is, names that
049: * may include components from different naming systems, name parameters to
050: * context methods may be considered differently as described below.
051: * </p>
052: * <p>
053: * In systems supporting federation, String name parameters are treated as
054: * composite names. When <code>Name</code> parameters are not instances of
055: * <code>CompositeName</code>, they are deemed to be compound names (<code>CompoundName</code>
056: * instances or subclasses of them). Also, when using <code>list()</code> or
057: * <code>listBindings()</code> to obtain a <code>NamingEnumeration</code>,
058: * all names in the enumeration are string representations of composite names.
059: * </p>
060: * <p>
061: * Where systems do not support federation, a service provider may treat name
062: * parameters to context methods and names found using
063: * <code>NamingEnumeration</code> may either as composite names or as compound
064: * names. See service provider documentation for details.
065: * </p>
066: * <p>
067: * Any <code>Name</code> parameter specified to a context method is owned by
068: * the caller and will remain unchanged, but applications should avoid modifying
069: * these <code>Name</code> objects while the operation has not completed. Any
070: * <code>Name</code> object returned by a context operation becomes owned by
071: * the caller.
072: * </p>
073: * <p>
074: * JNDI applications can provide preferences and configuration information, such
075: * as security details for authentication to a service, using JNDI environment
076: * properties. JNDI environment properties nearly all begin with "java.naming."
077: * except for provider-specific properties (explained below). All specified JNDI
078: * environment properties together comprise the context environment and methods
079: * are available for examining and manipulating that environment. The
080: * environment of a context may not necessarily contain all possible JNDI
081: * properties; for example, one or more may remain unspecified.
082: * </p>
083: * <p>
084: * The set of standard JNDI environment properties is:
085: *
086: * <pre>
087: * Property name Value type Notes
088: * ------------- ---------- -----
089: * java.naming.applet F
090: * java.naming.authoritative F
091: * java.naming.batchsize F
092: * java.naming.dns.url F
093: * java.naming.factory.control C see LdapContext
094: * java.naming.factory.initial F
095: * java.naming.factory.object C
096: * java.naming.factory.state C
097: * java.naming.factory.url.pkgs C
098: * java.naming.language F
099: * java.naming.provider.url F
100: * java.naming.referral F
101: * java.naming.security.authentication F
102: * java.naming.security.credentials F
103: * java.naming.security.principal F
104: * java.naming.security.protocol F
105: * </pre>
106: *
107: * </p>
108: * <p>
109: * For each property above marked with "C" for "concatenate", when encountered
110: * while searching sources of environment properties, values are combined into a
111: * single list separated by colons and becomes the resulting value of that
112: * property.
113: * </p>
114: * <p>
115: * For each property above marked with "F" for "first occurrence", when
116: * encountered while searching sources of environment properties, the first
117: * value encountered is the resulting value of that property. In the latter
118: * case, and with additional JNDI environment properties explained further
119: * below, the type and syntax of acceptable property values should be described
120: * in the corresponding documentation for the property. In particular, a
121: * property may accept a value consisting of several pieces of relevant
122: * information, but the search order and precedence for environment properties
123: * ensures that the entire value of the first occurrence of a given property is
124: * deemed the value to be used.
125: * </p>
126: * <p>
127: * Additional JNDI environment properties may be defined according to the needs
128: * of the particular service and/or service providers and a few guidelines
129: * should be followed when choosing appropriate names for them. Such additional
130: * properties comprise service-specific, feature-specific, or provider-specific
131: * properties.
132: * </p>
133: * <p>
134: * Service-specific JNDI properties may be used by all service providers that
135: * offer implementations for a given service and would include the service type
136: * in the property name prefix. For example, JNDI service providers for Java RMI
137: * should name their service-specific JNDI properties using prefix
138: * "java.naming.rmi.", or LDAP service providers should use prefix
139: * "java.naming.ldap.".
140: * </p>
141: * <p>
142: * Feature-specific JNDI properties may be used by all service providers
143: * offering implementations using a particular flavor of a feature and would
144: * include the feature name and the particular flavor name in the property name
145: * prefix. A common example is SASL used by several service providers for
146: * security; appropriate SASL feature-specific properties would use prefix
147: * "java.naming.security.sasl.".
148: * </p>
149: * <p>
150: * Provider-specific JNDI properties are used by only a single provider though a
151: * provider may offer more than one service provider implementation. The
152: * provider should ensure uniqueness of their provider properties, for example,
153: * an LDAP service provider from mycom might use a service provider package name
154: * such as "com.mycom.jndi.ldap." as their provider-specific prefix.
155: * </p>
156: * <p>
157: * JNDI environment properties can be specified in a <code>Hashtable</code>
158: * and passed as the environment parameter when creating an initial context.
159: * </p>
160: * <p>
161: * Two other important sources of JNDI environment properties are resource files
162: * provided by applications and applet parameters (each is considered as an
163: * application resource file) and by service provider implementations (provider
164: * resource files) in the format of Java properties files - see
165: * <code>java.util.Properties</code> class for details.
166: * </p>
167: * <p>
168: * At runtime, the application classpath and, where appropriate, the applet
169: * codebase attribute is used to locate the classes to run; when creating the
170: * first initial context, the JNDI also searches the same path for all files
171: * (application resource files) called "jndi.properties"; it is the classpath
172: * associated with the context <code>ClassLoader</code> (for example, the
173: * return value from <code>Thread.getContextClassLoader()</code> or from
174: * <code>ClassLoader.getSystemClassLoader()</code>) which is searched to get
175: * the resource files. Further, a path comprising the value of the "java.home"
176: * system property followed by "lib/jndi.properties" is checked for a readable
177: * file; if one exists, then that file is used as another application resource
178: * file. All application resource files found in the application classpath are
179: * examined, but JNDI properties set in a file found early will override the
180: * same properties also set in a file found later in the classpath.
181: * </p>
182: * <p>
183: * Provider resource files are located according to the package prefix for the
184: * service provider's initial context factory and context implementation class
185: * in which dot separator characters are converted into slash path separator
186: * characters to construct a filepath appended with "jndiprovider.properties".
187: * Consider the example where you have a service provider which supplies a
188: * context <code>org.apache.harmony.jndi.example.exampleCtx</code>. In this
189: * case the package prefix is <code>org.apache.harmony.jndi.example</code>.
190: * Substituting slash chars for dots & appending "jndiprovider.properties" gives
191: * you <code>org/apache/harmony/jndi/example/jndiprovider.properties</code>.
192: * </p>
193: * <p>
194: * An important part of service provider implementation is to specify certain
195: * standard JNDI properties that are using to locate any of the various factory
196: * classes needed for the implementation; these are:
197: *
198: * <pre>
199: * java.naming.factory.control
200: * java.naming.factory.object
201: * java.naming.factory.state
202: * java.naming.factory.url.pkgs - package prefixes used for URL contexts
203: * </pre>
204: *
205: * </p>
206: * <p>
207: * When searching for the above 4 properties only provider resource files should
208: * be examined. Although other properties may be specified in them for use by
209: * the service provider implementation, the JNDI ignores properties from these
210: * files other than those related to factories.
211: * </p>
212: * <p>
213: * It should be noted that a provider resource file's properties differ from
214: * those in application resource files in that their values are not incorporated
215: * into the environment. Instead, they are read when the following methods are
216: * invoked with <code>Context</code> and <code>Hashtable</code> parameters:
217: *
218: * <pre>
219: * ControlFactory.getControlInstance - uses java.naming.factory.control
220: * DirectoryManager.getObjectInstance - uses java.naming.factory.object
221: * DirectoryManager.getStateToBind - uses java.naming.factory.state
222: * NamingManager.getObjectInstance - uses java.naming.factory.object
223: * NamingManager.getStateToBind - uses java.naming.factory.state
224: * </pre>
225: *
226: * </p>
227: * <p>
228: * These methods use their <code>Hashtable</code> parameter to get the
229: * environment properties. Then they use the class loader of the
230: * <code>Context</code> parameter to look for the provider resource file. If
231: * the file is found, then the value of the required property is appended to the
232: * value of the required property in the environment. Note that it is appended
233: * for use by this method but the environment itself is unaffected.
234: * </p>
235: * <p>
236: * The <code>jndiprovider.properties</code> files may specify additional
237: * properties, but documentation for the service provider should clearly
238: * describe which properties are valid in this file and under what
239: * circumstances.
240: * </p>
241: * <p>
242: * To summarize the search order and precedence for JNDI environment properties,
243: * the earliest having highest precedence:
244: *
245: * <pre>
246: * 1. environment parameter used to initialize an initial context,
247: * 2. applet parameters, (only used if that environment param does not exist)
248: * 3. system properties, (only used if that environment and applet parameter
249: * do not exist)
250: * 4. application resource files.
251: * </pre>
252: *
253: * </p>
254: * <p>
255: * It should be noted that in the case of applet parameters and system
256: * properties only a subset of the properties are read. These are the following
257: * 7:
258: *
259: * <pre>
260: * java.naming.dns.url
261: * java.naming.factory.control
262: * java.naming.factory.initial
263: * java.naming.factory.object
264: * java.naming.factory.state
265: * java.naming.factory.url.pkgs
266: * java.naming.provider.url
267: * </pre>
268: *
269: * </p>
270: * <p>
271: * For a JNDI property found in more than one of those sources, if it is one of
272: * the JNDI factory list properties then values are joined into a
273: * colon-separated list, otherwise the first instance of a property defines the
274: * value to be used.
275: * </p>
276: * <p>
277: * The above search order and precedence applies when creating contexts for any
278: * class implementing the <code>Context</code> interface.
279: * </p>
280: * <p>
281: * Although a subcontext inherits the environment of its parent context,
282: * subsequent changes to either's environment has no direct effect on the other.
283: * However, applications should avoid dependency on when JNDI properties are
284: * used or verified as this depends on the service provider implementation. As
285: * the environment of a context can be examined by any object that has a
286: * reference to the context, care should be taken to assess the risk to any
287: * security details stored in the environment.
288: * </p>
289: * <p>
290: * Multithreaded access to a single <code>Context</code> instance is only safe
291: * when client code uses appropriate synchronization and locking.
292: * </p>
293: * <p>
294: * When a <code>NamingEnumeration</code> is returned by a <code>Context</code>
295: * method, the operation should not be considered complete, for concurrency
296: * purposes, if the NamingEnumeration is still being used or if any referrals
297: * are still being followed resulting from that operation.
298: * </p>
299: */
300: public interface Context {
301:
302: /**
303: * A constant containing environment property name "java.naming.applet". The
304: * property may remain unspecified or may be specified within the
305: * environment parameter used when creating an initial context. When this
306: * environment property is specified, its value must be the currently
307: * executing instance of <code>java.applet.Applet</code> to enable the
308: * operation of initial context creation to search applet parameters first
309: * for other environment properties which may have been specified, before
310: * searching for properties in the constructor environment parameter, system
311: * properties, and application resource files.
312: */
313: public static final String APPLET = "java.naming.applet"; //$NON-NLS-1$
314:
315: /**
316: * A constant containing environment property name
317: * "java.naming.authoritative". An application specifies this property to
318: * indicate whether naming requests must be made to the most authoritative
319: * naming service instance or not. The property may remain unspecified or
320: * may be specified with a string value. If unspecified, the property value
321: * is considered to be "false". A value of "true" means requests should be
322: * made to the most authoritative naming service replicas or caches that may
323: * be available. Any value other than "true" means requests may be made to
324: * any instance of the naming service which need not be, but may include,
325: * the most authoritative.
326: */
327: public static final String AUTHORITATIVE = "java.naming.authoritative"; //$NON-NLS-1$
328:
329: /**
330: * A constant containing environment property name "java.naming.batchsize".
331: * An application specifies this property to indicate a preference to
332: * receive operation results in batches of the given size from the service
333: * provider. The property may remain unspecified or may be specified with an
334: * integer expressed as a string value. If unspecified, the batch size of
335: * operation results is determined by the service provider. The service
336: * provider implementation may use or ignore the specified value.
337: */
338: public static final String BATCHSIZE = "java.naming.batchsize"; //$NON-NLS-1$
339:
340: /**
341: * A constant containing environment property name "java.naming.dns.url".
342: * The property specifies a DNS-scheme URL including the DNS host including
343: * domain names, if any; for example, "dns://9.28.36.7/apache.org". If the
344: * application uses any JNDI URL with DNS names and a search for this
345: * property fails, then the naming operation will throw a
346: * <code>ConfigurationException</code>.
347: */
348: public static final String DNS_URL = "java.naming.dns.url"; //$NON-NLS-1$
349:
350: /**
351: * A constant containing environment property name
352: * "java.naming.factory.initial". The property specifies the name of the
353: * factory class, fully-qualified, that will be used to create an initial
354: * context; for example, "mycom.jndi.testing.spi.DazzleContextFactory". If
355: * the property is not specified, any operation requiring an initial context
356: * will throw a <code>NoInitialContextException</code>.
357: */
358: public static final String INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial"; //$NON-NLS-1$
359:
360: /**
361: * A constant containing environment property name "java.naming.language".
362: * The property indicates the preferred language for operations with the
363: * service provider. The property may remain unspecified or should be a
364: * string comprising a list of language tags according to RFC 1766 separated
365: * by colons. When not specified, the language preference is selected by the
366: * service provider.
367: */
368: public static final String LANGUAGE = "java.naming.language"; //$NON-NLS-1$
369:
370: /**
371: * A constant containing environment property name
372: * "java.naming.factory.object". The property specifies a list of object
373: * factories to be used when the application requests an instance of a
374: * specified object. The value is a string comprising a list of fully
375: * qualified object factory class names separated by colons.
376: */
377: public static final String OBJECT_FACTORIES = "java.naming.factory.object"; //$NON-NLS-1$
378:
379: /**
380: * A constant containing environment property name
381: * "java.naming.provider.url". The property specifies configuration options
382: * for use by the a service provider. The property may remain unspecified or
383: * should be a URL string; for example, "ldap://ahost.myfirm.com:389". If
384: * not specified, the service provider selects its default configuration.
385: */
386: public static final String PROVIDER_URL = "java.naming.provider.url"; //$NON-NLS-1$
387:
388: /**
389: * A constant containing environment property name "java.naming.referral".
390: * The property specifies how the service provider should process any
391: * referrals encountered during a naming operation. The property may remain
392: * unspecified or specified as one of the following strings:
393: * <ul>
394: * <li>"follow" service provider should always follow referrals</li>
395: * <li>"ignore" service provider should ignore referrals</li>
396: * <li>"throw" service provider should throw ReferralException if it
397: * encounters a referral</li>
398: * </ul>
399: * When not specified, the service provider selects a default value.
400: */
401: public static final String REFERRAL = "java.naming.referral"; //$NON-NLS-1$
402:
403: /**
404: * A constant containing environment property name
405: * "java.naming.security.authentication". The property specifies the
406: * security level to be used in naming operations. The property may remain
407: * unspecified or be one of the strings "none", "simple", "strong". When not
408: * specified, the service provider selects a default value.
409: */
410: public static final String SECURITY_AUTHENTICATION = "java.naming.security.authentication"; //$NON-NLS-1$
411:
412: /**
413: * A constant containing environment property name
414: * "java.naming.security.credentials". The property specifies credentials of
415: * the security principal so that the caller can be authenticated to the
416: * naming service. The property may remain unspecified or be a value
417: * according to the authentication scheme controlling access to the service.
418: * When not specified, the service provider determines how to respond to
419: * service requests affected by the lack of security credentials.
420: */
421: public static final String SECURITY_CREDENTIALS = "java.naming.security.credentials"; //$NON-NLS-1$
422:
423: /**
424: * A constant containing environment property name
425: * "java.naming.security.principal". The property the name of the security
426: * principal to be used when the caller needs to be authenticated to the
427: * naming service. The property may remain unspecified or be a value
428: * according to the authentication scheme controlling access to the service.
429: * When not specified, the service provider determines how to respond to
430: * service requests affected by the lack of a security principal.
431: */
432: public static final String SECURITY_PRINCIPAL = "java.naming.security.principal"; //$NON-NLS-1$
433:
434: /**
435: * A constant containing environment property name
436: * "java.naming.security.protocol". The property the name of the security
437: * protocol to be used with the naming service. The property may remain
438: * unspecified or be specified as a string according to the service provider
439: * implementation. When not specified, the service provider determines how
440: * to respond to service requests.
441: */
442: public static final String SECURITY_PROTOCOL = "java.naming.security.protocol"; //$NON-NLS-1$
443:
444: /**
445: * A constant containing environment property name
446: * "java.naming.factory.state". The property specifies a list of state
447: * factories to be used when the application requests the state of a
448: * specified object. The value is a string comprising a list of fully
449: * qualified state factory class names separated by colons. The property may
450: * remain unspecified.
451: */
452: public static final String STATE_FACTORIES = "java.naming.factory.state"; //$NON-NLS-1$
453:
454: /**
455: * A constant containing environment property name
456: * "java.naming.factory.url.pkgs". The property specifies a list of package
457: * prefixes that are used to load URL context factories. The value is a
458: * string comprising a list of package prefixes for class names of URL
459: * context factory classes separated by colons. The property may remain
460: * unspecified. In any case, prefix "com.sun.jndi.url" is automatically
461: * added to the list of specified package prefixes or used as the only
462: * package prefix when the property is unspecified.
463: */
464: public static final String URL_PKG_PREFIXES = "java.naming.factory.url.pkgs"; //$NON-NLS-1$
465:
466: /**
467: * Adds or replaces the environment property specified by the non-null
468: * string parameter into the environment of this context with the specified
469: * object value. Returns the previous property value if replaced, or null if
470: * the property did not exist in the environment.
471: *
472: * @param s
473: * the name of the property to add
474: * @param o
475: * the value of the property to add
476: * @return the previous property value if replaced, or null if the property
477: * did not exist in the environment.
478: * @throws NamingException
479: * if an error occurs.
480: */
481: public Object addToEnvironment(String s, Object o)
482: throws NamingException;
483:
484: /**
485: * Binds the specified name to the specified object in this context. The
486: * specified name may not be null. The specified object may be null when a
487: * name bound to a null object is meaningful in the semantics of the
488: * underlying naming system, otherwise a <code>NamingException</code> is
489: * thrown.
490: *
491: * @param n
492: * a <code>Name</code>, may not be null
493: * @param o
494: * an object to bind with the name, may be null
495: * @throws NamingException
496: * if an error occurs.
497: */
498: public void bind(Name n, Object o) throws NamingException;
499:
500: /**
501: * Binds the specified name to the specified object in this context. The
502: * specified name may not be null. The specified object may be null when a
503: * name bound to a null object is meaningful in the semantics of the
504: * underlying naming system, otherwise a <code>NamingException</code> is
505: * thrown.
506: *
507: * @param s
508: * a name in string, may not be null
509: * @param o
510: * an object to bind with the name, may be null
511: * @throws NamingException
512: * if an error occurs.
513: */
514: public void bind(String s, Object o) throws NamingException;
515:
516: /**
517: * Closes this context. The result of any further operations on a closed
518: * context is undefined.
519: *
520: * @throws NamingException
521: * if an error occurs.
522: */
523: public void close() throws NamingException;
524:
525: /**
526: * Combines two names into a composite name according to the syntax for this
527: * context. The name <code>pfx</code> is expected to be the name of one or
528: * more of the immediate parent contexts of this context. The name
529: * <code>n</code> is a name relative to this context. Neither
530: * <code>pfx</code> nor <code>n</code> may be null. The combined result
531: * is a name which is relative to the specified parent context names.
532: *
533: * @param n
534: * a <code>Name</code>, may not be null
535: * @param pfx
536: * a <code>Name</code> serves as prefix, may not be null
537: * @return the combined name
538: * @throws NamingException
539: * if an error occurs.
540: */
541: public Name composeName(Name n, Name pfx) throws NamingException;
542:
543: /**
544: * Combines two names into a composite name according to the syntax for this
545: * context. The name <code>pfx</code> is expected to be the name of one or
546: * more of the immediate parent contexts of this context. The name
547: * <code>s</code> is a name relative to this context. Neither
548: * <code>pfx</code> nor <code>s</code> may be null. The combined result
549: * is a name which is relative to the specified parent context names.
550: *
551: * @param s
552: * a name in string, may not be null
553: * @param pfx
554: * a name in string, serves as prefix, may not be null
555: * @return the combined name in string
556: * @throws NamingException
557: * if an error occurs.
558: */
559: public String composeName(String s, String pfx)
560: throws NamingException;
561:
562: /**
563: * Creates a new context with the specified name as a child of this context
564: * and creates a binding for the name with the new context object in this
565: * context. This is analogous to creating a new lower level in a
566: * hierarchical naming system.
567: *
568: * @param n
569: * the name of the new subcontext
570: * @return the created subcontext
571: * @throws NamingException
572: * if an error occurs.
573: */
574: public Context createSubcontext(Name n) throws NamingException;
575:
576: /**
577: * Creates a new context with the specified name as a child of this context
578: * and creates a binding for the name with the new context object in this
579: * context. This is analogous to creating a new lower level in a
580: * hierarchical naming system.
581: *
582: * @param s
583: * the name of the new subcontext, in string
584: * @return the created subcontext
585: * @throws NamingException
586: * if an error occurs.
587: */
588: public Context createSubcontext(String s) throws NamingException;
589:
590: /**
591: * Removes a child context with the specified name from this context
592: * together with any attributes associated with that name. If the specified
593: * context does not exist, but intervening contexts do exist, then the
594: * operation is is considered to succeed.
595: * <p>
596: * Care must be taken with composite names crossing multiple naming systems.
597: * A composite name containing a name component which is bound to an object
598: * in a different naming system cannot be used to destroy that name
599: * subcontext because the subcontext is not of the same type as the context
600: * containing the binding. <code>Unbind()</code> can be used to destroy
601: * the binding of the specified name in this context to the object in the
602: * other naming system. To remove the context object in the other naming
603: * system, first obtain a context belonging to the other naming system, then
604: * use <code>destroySubcontext()</code> on that context.
605: * </p>
606: *
607: * @param n
608: * the name of the subcontext to destroy
609: * @throws NamingException
610: * if an error occurs.
611: */
612: public void destroySubcontext(Name n) throws NamingException;
613:
614: /**
615: * Removes a child context with the specified name from this context
616: * together with any attributes associated with that name. If the specified
617: * context does not exist, but intervening contexts do exist, then the
618: * operation is considered to succeed.
619: * <p>
620: * Care must be taken with composite names crossing multiple naming systems.
621: * A composite name containing a name component which is bound to an object
622: * in a different naming system cannot be used to destroy that name
623: * subcontext because the subcontext is not of the same type as the context
624: * containing the binding. <code>Unbind()</code> can be used to destroy
625: * the binding of the specified name in this context to the object in the
626: * other naming system. To remove the context object in the other naming
627: * system, first obtain a context belonging to the other naming system, then
628: * use <code>destroySubcontext()</code> on that context.
629: * </p>
630: *
631: * @param s
632: * the name of the subcontext to destroy
633: * @throws NamingException
634: * if an error occurs.
635: */
636: public void destroySubcontext(String s) throws NamingException;
637:
638: /**
639: * Returns a non-null reference to the current environment properties for
640: * this context. The only proper ways to modify the properties for this
641: * context are using the <code>addToEnvironment()</code> and
642: * <code>removeFromEnvironment()</code> methods.
643: *
644: * @return a non-null reference to the current environment properties for
645: * this context, which should not be modified
646: * @throws NamingException
647: * if an error occurs.
648: */
649: public Hashtable<?, ?> getEnvironment() throws NamingException;
650:
651: /**
652: * Returns the complete name as a string for this context in the namespace.
653: * For example, in a namespace accessed using a file system service provider
654: * on a computer running the Windows operating system,
655: * <code>getNameInNamespace()</code> will return a string comprising the
656: * current working disk drive such as "F:\". The returned name is never null
657: * and should not be used in any naming operations.
658: *
659: * @return the complete name as a string for this context in the namespace
660: * @throws NamingException
661: * if an error occurs.
662: * @throws OperationNotSupportedException
663: * in cases of naming systems where a full name has no meaning.
664: */
665: public String getNameInNamespace() throws NamingException;
666:
667: /**
668: * Returns a parser object for the named context. When using a federation of
669: * naming systems in which each has its own rules for parsing names for its
670: * namespace, each naming system will have a different parser. The parser
671: * for a given context can parse a name composed of several components into
672: * atomic components according to the rules for the naming system associated
673: * with the specified context.
674: *
675: * @param n
676: * a <code>Name</code>
677: * @return a parser object for the named context
678: * @throws NamingException
679: * if an error occurs.
680: */
681: public NameParser getNameParser(Name n) throws NamingException;
682:
683: /**
684: * Returns a parser object for the named context. When using a federation of
685: * naming systems in which each has its own rules for parsing names for its
686: * namespace, each naming system will have a different parser. The parser
687: * for a given context can parse a name composed of several components into
688: * atomic components according to the rules for the naming system associated
689: * with the specified context.
690: *
691: * @param s
692: * a name in string
693: * @return a parser object for the named context
694: * @throws NamingException
695: * if an error occurs.
696: */
697: public NameParser getNameParser(String s) throws NamingException;
698:
699: /**
700: * Returns an enumeration of the bindings of the context for the specified
701: * name excluding any bindings for any subcontexts. If any binding for the
702: * context is changed before closing the enumeration, the state of the
703: * enumeration is undefined. Each element of the enumeration is a
704: * <code>NameClassPair</code> object.
705: *
706: * @param n
707: * a <code>Name</code>
708: * @return an enumeration of the bindings of the context for the specified
709: * name excluding any bindings for any subcontexts
710: * @throws NamingException
711: * if an error occurs.
712: */
713: public NamingEnumeration<NameClassPair> list(Name n)
714: throws NamingException;
715:
716: /**
717: * Returns an enumeration of the bindings of the context for the specified
718: * name excluding any bindings for any subcontexts. If any binding for the
719: * context is changed before closing the enumeration, the state of the
720: * enumeration is undefined. Each element of the enumeration is a
721: * <code>NameClassPair</code> object.
722: *
723: * @param s
724: * a name in string
725: * @return an enumeration of the bindings of the context for the specified
726: * name excluding any bindings for any subcontexts
727: * @throws NamingException
728: * if an error occurs.
729: */
730: public NamingEnumeration<NameClassPair> list(String s)
731: throws NamingException;
732:
733: /**
734: * Returns an enumeration of the bindings of the context for the specified
735: * name excluding any bindings for any subcontexts. If any binding for the
736: * context is changed before closing the enumeration, the state of the
737: * enumeration is undefined. Each element of the enumeration is a
738: * <code>Binding</code> object.
739: *
740: * @param n
741: * a <code>Name</code>
742: * @return an enumeration of the bindings of the context for the specified
743: * name excluding any bindings for any subcontexts
744: * @throws NamingException
745: * if an error occurs.
746: */
747: public NamingEnumeration<Binding> listBindings(Name n)
748: throws NamingException;
749:
750: /**
751: * Returns an enumeration of the bindings of the context for the specified
752: * name excluding any bindings for any subcontexts. If any binding for the
753: * context is changed before closing the enumeration, the state of the
754: * enumeration is undefined. Each element of the enumeration is a
755: * <code>Binding</code> object.
756: *
757: * @param s
758: * a name in string
759: * @return an enumeration of the bindings of the context for the specified
760: * name excluding any bindings for any subcontexts
761: * @throws NamingException
762: * if an error occurs.
763: */
764: public NamingEnumeration<Binding> listBindings(String s)
765: throws NamingException;
766:
767: /**
768: * Returns the object bound to the specified name in this context. If the
769: * specified name is empty, a new instance of this context is returned,
770: * complete with its own environment properties.
771: *
772: * @param n
773: * a <code>Name</code> to lookup
774: * @return the object bound to the specified name in this context
775: * @throws NamingException
776: * if an error occurs.
777: */
778: public Object lookup(Name n) throws NamingException;
779:
780: /**
781: * Returns the object bound to the specified name in this context. If the
782: * specified name is empty, a new instance of this context is returned,
783: * complete with its own environment properties.
784: *
785: * @param s
786: * a name to lookup
787: * @return the object bound to the specified name in this context
788: * @throws NamingException
789: * if an error occurs.
790: */
791: public Object lookup(String s) throws NamingException;
792:
793: /**
794: * Returns the object bound to the specified name in this context by
795: * following any links. If the specified name is not a link, then the object
796: * is returned.
797: *
798: * @param n
799: * a <code>Name</code> to lookup
800: * @return the object bound to the specified name in this context by
801: * following any links
802: * @throws NamingException
803: * if an error occurs.
804: */
805: public Object lookupLink(Name n) throws NamingException;
806:
807: /**
808: * Returns the object bound to the specified name in this context by
809: * following any links. If the specified name is not a link, then the object
810: * is returned.
811: *
812: * @param s
813: * a name in string to lookup
814: * @return the object bound to the specified name in this context by
815: * following any links
816: * @throws NamingException
817: * if an error occurs.
818: */
819: public Object lookupLink(String s) throws NamingException;
820:
821: /**
822: * Binds the specified name to the specified object, replacing any existing
823: * binding for the specified name. The specified name may not be empty. The
824: * specified object may be null.
825: *
826: * @param n
827: * a <code>Name</code> to rebind, may not be null
828: * @param o
829: * an object to bind with the name, may be null
830: * @throws NamingException
831: * if an error occurs.
832: */
833: public void rebind(Name n, Object o) throws NamingException;
834:
835: /**
836: * Binds the specified name to the specified object, replacing any existing
837: * binding for the specified name. The specified name may not be empty. The
838: * specified object may be null.
839: *
840: * @param s
841: * a name in string to rebind, may not be null
842: * @param o
843: * an object tobind with the name, may be null
844: * @throws NamingException
845: * if an error occurs.
846: */
847: public void rebind(String s, Object o) throws NamingException;
848:
849: /**
850: * Removes the environment property specified by the non-null parameter from
851: * the environment of this context. Returns the value that the property had
852: * before removal, or null if the property did not exist in the environment.
853: *
854: * @param s
855: * a property name
856: * @return the value that the property had before removal, or null if the
857: * property did not exist in the environment
858: * @throws NamingException
859: * if an error occurs.
860: */
861: public Object removeFromEnvironment(String s)
862: throws NamingException;
863:
864: /**
865: * Binds a specified new name to the object, and any attributes, previously
866: * bound to the specified old name. The old name is removed from the
867: * bindings for this context.
868: *
869: * @param nOld
870: * the old name
871: * @param nNew
872: * the new name
873: * @throws NameAlreadyBoundException
874: * if the new is already bound
875: * @throws NamingException
876: * if an error occurs.
877: */
878: public void rename(Name nOld, Name nNew) throws NamingException;
879:
880: /**
881: * Binds a specified new name to the object, and any attributes, previously
882: * bound to the specified old name. The old name is removed from the
883: * bindings for this context. Neither the new nor the old name may be empty.
884: *
885: * @param sOld
886: * the old name in string
887: * @param sNew
888: * the new name in string
889: * @throws NameAlreadyBoundException
890: * if the new is already bound
891: * @throws NamingException
892: * if an error occurs.
893: */
894: public void rename(String sOld, String sNew) throws NamingException;
895:
896: /**
897: * Removes the terminal atomic name component of the specified name from the
898: * bindings in this context, together with any attributes associated with
899: * the terminal atomic name. Providing that other parts of the specified
900: * name exist in this context's bindings, the operation succeeds whether or
901: * not the terminal atomic name exists, otherwise a
902: * <code>NameNotFoundException</code> is thrown. Any intermediate contexts
903: * remain unchanged.
904: *
905: * @param n
906: * a <code>Name</code> to unbind
907: * @throws NamingException
908: * if an error occurs.
909: */
910: public void unbind(Name n) throws NamingException;
911:
912: /**
913: * Removes the terminal atomic name component of the specified name from the
914: * bindings in this context, together with any attributes associated with
915: * the terminal atomic name. Providing that other parts of the specified
916: * name exist in this context's bindings, the operation succeeds whether or
917: * not the terminal atomic name exists, otherwise a
918: * <code>NameNotFoundException</code> is thrown. Any intermediate contexts
919: * remain unchanged.
920: *
921: * @param s
922: * a name in string to unbind
923: * @throws NamingException
924: * if an error occurs.
925: */
926: public void unbind(String s) throws NamingException;
927:
928: }
|