0001 /*
0002 * Copyright 1999-2006 Sun Microsystems, Inc. All Rights Reserved.
0003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004 *
0005 * This code is free software; you can redistribute it and/or modify it
0006 * under the terms of the GNU General Public License version 2 only, as
0007 * published by the Free Software Foundation. Sun designates this
0008 * particular file as subject to the "Classpath" exception as provided
0009 * by Sun in the LICENSE file that accompanied this code.
0010 *
0011 * This code is distributed in the hope that it will be useful, but WITHOUT
0012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014 * version 2 for more details (a copy is included in the LICENSE file that
0015 * accompanied this code).
0016 *
0017 * You should have received a copy of the GNU General Public License version
0018 * 2 along with this work; if not, write to the Free Software Foundation,
0019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020 *
0021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022 * CA 95054 USA or visit www.sun.com if you need additional information or
0023 * have any questions.
0024 */
0025
0026 package javax.naming;
0027
0028 import java.util.Hashtable;
0029
0030 /**
0031 * This interface represents a naming context, which
0032 * consists of a set of name-to-object bindings.
0033 * It contains methods for examining and updating these bindings.
0034 * <p>
0035 * <h4>Names</h4>
0036 * Each name passed as an argument to a <tt>Context</tt> method is relative
0037 * to that context. The empty name is used to name the context itself.
0038 * A name parameter may never be null.
0039 * <p>
0040 * Most of the methods have overloaded versions with one taking a
0041 * <code>Name</code> parameter and one taking a <code>String</code>.
0042 * These overloaded versions are equivalent in that if
0043 * the <code>Name</code> and <code>String</code> parameters are just
0044 * different representations of the same name, then the overloaded
0045 * versions of the same methods behave the same.
0046 * In the method descriptions below, only one version is fully documented.
0047 * The second version instead has a link to the first: the same
0048 * documentation applies to both.
0049 * <p>
0050 * For systems that support federation, <tt>String</tt> name arguments to
0051 * <tt>Context</tt> methods are composite names. Name arguments that are
0052 * instances of <tt>CompositeName</tt> are treated as composite names,
0053 * while <tt>Name</tt> arguments that are not instances of
0054 * <tt>CompositeName</tt> are treated as compound names (which might be
0055 * instances of <tt>CompoundName</tt> or other implementations of compound
0056 * names). This allows the results of <tt>NameParser.parse()</tt> to be used as
0057 * arguments to the <tt>Context</tt> methods.
0058 * Prior to JNDI 1.2, all name arguments were treated as composite names.
0059 *<p>
0060 * Furthermore, for systems that support federation, all names returned
0061 * in a <tt>NamingEnumeration</tt>
0062 * from <tt>list()</tt> and <tt>listBindings()</tt> are composite names
0063 * represented as strings.
0064 * See <tt>CompositeName</tt> for the string syntax of names.
0065 *<p>
0066 * For systems that do not support federation, the name arguments (in
0067 * either <tt>Name</tt> or <tt>String</tt> forms) and the names returned in
0068 * <tt>NamingEnumeration</tt> may be names in their own namespace rather than
0069 * names in a composite namespace, at the discretion of the service
0070 * provider.
0071 *<p>
0072 *<h4>Exceptions</h4>
0073 * All the methods in this interface can throw a <tt>NamingException</tt> or
0074 * any of its subclasses. See <tt>NamingException</tt> and their subclasses
0075 * for details on each exception.
0076 *<p>
0077 *<h4>Concurrent Access</h4>
0078 * A Context instance is not guaranteed to be synchronized against
0079 * concurrent access by multiple threads. Threads that need to access
0080 * a single Context instance concurrently should synchronize amongst
0081 * themselves and provide the necessary locking. Multiple threads
0082 * each manipulating a different Context instance need not
0083 * synchronize. Note that the {@link #lookup(Name) <tt>lookup</tt>}
0084 * method, when passed an empty name, will return a new Context instance
0085 * representing the same naming context.
0086 *<p>
0087 * For purposes of concurrency control,
0088 * a Context operation that returns a <tt>NamingEnumeration</tt> is
0089 * not considered to have completed while the enumeration is still in
0090 * use, or while any referrals generated by that operation are still
0091 * being followed.
0092 *
0093 *<p>
0094 *<h4>Parameters</h4>
0095 * A <tt>Name</tt> parameter passed to any method of the
0096 * <tt>Context</tt> interface or one of its subinterfaces
0097 * will not be modified by the service provider.
0098 * The service provider may keep a reference to it
0099 * for the duration of the operation, including any enumeration of the
0100 * method's results and the processing of any referrals generated.
0101 * The caller should not modify the object during this time.
0102 * A <tt>Name</tt> returned by any such method is owned by the caller.
0103 * The caller may subsequently modify it; the service provider may not.
0104 *
0105 *<p>
0106 *<h4>Environment Properties</h4>
0107 *<p>
0108 * JNDI applications need a way to communicate various preferences
0109 * and properties that define the environment in which naming and
0110 * directory services are accessed. For example, a context might
0111 * require specification of security credentials in order to access
0112 * the service. Another context might require that server configuration
0113 * information be supplied. These are referred to as the <em>environment</em>
0114 * of a context. The <tt>Context</tt> interface provides methods for
0115 * retrieving and updating this environment.
0116 *<p>
0117 * The environment is inherited from the parent context as
0118 * context methods proceed from one context to the next. Changes to
0119 * the environment of one context do not directly affect those
0120 * of other contexts.
0121 *<p>
0122 * It is implementation-dependent when environment properties are used
0123 * and/or verified for validity. For example, some of the
0124 * security-related properties are used by service providers to "log in"
0125 * to the directory. This login process might occur at the time the
0126 * context is created, or the first time a method is invoked on the
0127 * context. When, and whether this occurs at all, is
0128 * implementation-dependent. When environment properties are added or
0129 * removed from the context, verifying the validity of the changes is again
0130 * implementation-dependent. For example, verification of some properties
0131 * might occur at the time the change is made, or at the time the next
0132 * operation is performed on the context, or not at all.
0133 *<p>
0134 * Any object with a reference to a context may examine that context's
0135 * environment. Sensitive information such as clear-text
0136 * passwords should not be stored there unless the implementation is
0137 * known to protect it.
0138 *
0139 *<p>
0140 *<a name=RESOURCEFILES></a>
0141 *<h4>Resource Files</h4>
0142 *<p>
0143 * To simplify the task of setting up the environment
0144 * required by a JNDI application,
0145 * application components and service providers may be distributed
0146 * along with <em>resource files.</em>
0147 * A JNDI resource file is a file in the properties file format (see
0148 * {@link java.util.Properties#load <tt>java.util.Properties</tt>}),
0149 * containing a list of key/value pairs.
0150 * The key is the name of the property (e.g. "java.naming.factory.object")
0151 * and the value is a string in the format defined
0152 * for that property. Here is an example of a JNDI resource file:
0153 *
0154 * <blockquote><tt><pre>
0155 * java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
0156 * java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
0157 * java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
0158 * </pre></tt></blockquote>
0159 *
0160 * The JNDI class library reads the resource files and makes the property
0161 * values freely available. Thus JNDI resource files should be considered
0162 * to be "world readable", and sensitive information such as clear-text
0163 * passwords should not be stored there.
0164 *<p>
0165 * There are two kinds of JNDI resource files:
0166 * <em>provider</em> and <em>application</em>.
0167 *
0168 * <h5>Provider Resource Files</h5>
0169 *
0170 * Each service provider has an optional resource that lists properties
0171 * specific to that provider. The name of this resource is:
0172 * <blockquote>
0173 * [<em>prefix</em>/]<tt>jndiprovider.properties</tt>
0174 * </blockquote>
0175 * where <em>prefix</em> is
0176 * the package name of the provider's context implementation(s),
0177 * with each period (".") converted to a slash ("/").
0178 *
0179 * For example, suppose a service provider defines a context
0180 * implementation with class name <tt>com.sun.jndi.ldap.LdapCtx</tt>.
0181 * The provider resource for this provider is named
0182 * <tt>com/sun/jndi/ldap/jndiprovider.properties</tt>. If the class is
0183 * not in a package, the resource's name is simply
0184 * <tt>jndiprovider.properties</tt>.
0185 *
0186 * <p>
0187 * <a name=LISTPROPS></a>
0188 * Certain methods in the JNDI class library make use of the standard
0189 * JNDI properties that specify lists of JNDI factories:
0190 * <ul>
0191 * <li>java.naming.factory.object
0192 * <li>java.naming.factory.state
0193 * <li>java.naming.factory.control
0194 * <li>java.naming.factory.url.pkgs
0195 * </ul>
0196 * The JNDI library will consult the provider resource file
0197 * when determining the values of these properties.
0198 * Properties other than these may be set in the provider
0199 * resource file at the discretion of the service provider.
0200 * The service provider's documentation should clearly state which
0201 * properties are allowed; other properties in the file will be ignored.
0202 *
0203 * <h5>Application Resource Files</h5>
0204 *
0205 * When an application is deployed, it will generally have several
0206 * codebase directories and JARs in its classpath. Similarly, when an
0207 * applet is deployed, it will have a codebase and archives specifying
0208 * where to find the applet's classes. JNDI locates (using
0209 * {@link ClassLoader#getResources <tt>ClassLoader.getResources()</tt>})
0210 * all <em>application resource files</em> named <tt>jndi.properties</tt>
0211 * in the classpath.
0212 * In addition, if the file <i>java.home</i><tt>/lib/jndi.properties</tt>
0213 * exists and is readable,
0214 * JNDI treats it as an additional application resource file.
0215 * (<i>java.home</i> indicates the
0216 * directory named by the <tt>java.home</tt> system property.)
0217 * All of the properties contained in these files are placed
0218 * into the environment of the initial context. This environment
0219 * is then inherited by other contexts.
0220 *
0221 * <p>
0222 * For each property found in more than one application resource file,
0223 * JNDI uses the first value found or, in a few cases where it makes
0224 * sense to do so, it concatenates all of the values (details are given
0225 * below).
0226 * For example, if the "java.naming.factory.object" property is found in
0227 * three <tt>jndi.properties</tt> resource files, the
0228 * list of object factories is a concatenation of the property
0229 * values from all three files.
0230 * Using this scheme, each deployable component is responsible for
0231 * listing the factories that it exports. JNDI automatically
0232 * collects and uses all of these export lists when searching for factory
0233 * classes.
0234 *
0235 * <h5>Search Algorithm for Properties</h5>
0236 *
0237 * When JNDI constructs an initial context, the context's environment
0238 * is initialized with properties defined in the environment parameter
0239 * passed to the constructor, the system properties, the applet parameters,
0240 * and the application resource files. See
0241 * <a href=InitialContext.html#ENVIRONMENT><tt>InitialContext</tt></a>
0242 * for details.
0243 * This initial environment is then inherited by other context instances.
0244 *
0245 * <p>
0246 * When the JNDI class library needs to determine
0247 * the value of a property, it does so by merging
0248 * the values from the following two sources, in order:
0249 * <ol>
0250 * <li>The environment of the context being operated on.
0251 * <li>The provider resource file (<tt>jndiprovider.properties</tt>)
0252 * for the context being operated on.
0253 * </ol>
0254 * For each property found in both of these two sources,
0255 * JNDI determines the property's value as follows. If the property is
0256 * one of the standard JNDI properties that specify a list of JNDI
0257 * factories (listed <a href=#LISTPROPS>above</a>), the values are
0258 * concatenated into a single colon-separated list. For other
0259 * properties, only the first value found is used.
0260 *
0261 * <p>
0262 * When a service provider needs to determine the value of a property,
0263 * it will generally take that value directly from the environment.
0264 * A service provider may define provider-specific properties
0265 * to be placed in its own provider resource file. In that
0266 * case it should merge values as described in the previous paragraph.
0267 *
0268 * <p>
0269 * In this way, each service provider developer can specify a list of
0270 * factories to use with that service provider. These can be modified by
0271 * the application resources specified by the deployer of the application
0272 * or applet, which in turn can be modified by the user.
0273 *
0274 * @author Rosanna Lee
0275 * @author Scott Seligman
0276 * @author R. Vasudevan
0277 * @version 1.20 07/05/05
0278 *
0279 * @since 1.3
0280 */
0281
0282 public interface Context {
0283
0284 /**
0285 * Retrieves the named object.
0286 * If <tt>name</tt> is empty, returns a new instance of this context
0287 * (which represents the same naming context as this context, but its
0288 * environment may be modified independently and it may be accessed
0289 * concurrently).
0290 *
0291 * @param name
0292 * the name of the object to look up
0293 * @return the object bound to <tt>name</tt>
0294 * @throws NamingException if a naming exception is encountered
0295 *
0296 * @see #lookup(String)
0297 * @see #lookupLink(Name)
0298 */
0299 public Object lookup(Name name) throws NamingException;
0300
0301 /**
0302 * Retrieves the named object.
0303 * See {@link #lookup(Name)} for details.
0304 * @param name
0305 * the name of the object to look up
0306 * @return the object bound to <tt>name</tt>
0307 * @throws NamingException if a naming exception is encountered
0308 */
0309 public Object lookup(String name) throws NamingException;
0310
0311 /**
0312 * Binds a name to an object.
0313 * All intermediate contexts and the target context (that named by all
0314 * but terminal atomic component of the name) must already exist.
0315 *
0316 * @param name
0317 * the name to bind; may not be empty
0318 * @param obj
0319 * the object to bind; possibly null
0320 * @throws NameAlreadyBoundException if name is already bound
0321 * @throws javax.naming.directory.InvalidAttributesException
0322 * if object did not supply all mandatory attributes
0323 * @throws NamingException if a naming exception is encountered
0324 *
0325 * @see #bind(String, Object)
0326 * @see #rebind(Name, Object)
0327 * @see javax.naming.directory.DirContext#bind(Name, Object,
0328 * javax.naming.directory.Attributes)
0329 */
0330 public void bind(Name name, Object obj) throws NamingException;
0331
0332 /**
0333 * Binds a name to an object.
0334 * See {@link #bind(Name, Object)} for details.
0335 *
0336 * @param name
0337 * the name to bind; may not be empty
0338 * @param obj
0339 * the object to bind; possibly null
0340 * @throws NameAlreadyBoundException if name is already bound
0341 * @throws javax.naming.directory.InvalidAttributesException
0342 * if object did not supply all mandatory attributes
0343 * @throws NamingException if a naming exception is encountered
0344 */
0345 public void bind(String name, Object obj) throws NamingException;
0346
0347 /**
0348 * Binds a name to an object, overwriting any existing binding.
0349 * All intermediate contexts and the target context (that named by all
0350 * but terminal atomic component of the name) must already exist.
0351 *
0352 * <p> If the object is a <tt>DirContext</tt>, any existing attributes
0353 * associated with the name are replaced with those of the object.
0354 * Otherwise, any existing attributes associated with the name remain
0355 * unchanged.
0356 *
0357 * @param name
0358 * the name to bind; may not be empty
0359 * @param obj
0360 * the object to bind; possibly null
0361 * @throws javax.naming.directory.InvalidAttributesException
0362 * if object did not supply all mandatory attributes
0363 * @throws NamingException if a naming exception is encountered
0364 *
0365 * @see #rebind(String, Object)
0366 * @see #bind(Name, Object)
0367 * @see javax.naming.directory.DirContext#rebind(Name, Object,
0368 * javax.naming.directory.Attributes)
0369 * @see javax.naming.directory.DirContext
0370 */
0371 public void rebind(Name name, Object obj) throws NamingException;
0372
0373 /**
0374 * Binds a name to an object, overwriting any existing binding.
0375 * See {@link #rebind(Name, Object)} for details.
0376 *
0377 * @param name
0378 * the name to bind; may not be empty
0379 * @param obj
0380 * the object to bind; possibly null
0381 * @throws javax.naming.directory.InvalidAttributesException
0382 * if object did not supply all mandatory attributes
0383 * @throws NamingException if a naming exception is encountered
0384 */
0385 public void rebind(String name, Object obj) throws NamingException;
0386
0387 /**
0388 * Unbinds the named object.
0389 * Removes the terminal atomic name in <code>name</code>
0390 * from the target context--that named by all but the terminal
0391 * atomic part of <code>name</code>.
0392 *
0393 * <p> This method is idempotent.
0394 * It succeeds even if the terminal atomic name
0395 * is not bound in the target context, but throws
0396 * <tt>NameNotFoundException</tt>
0397 * if any of the intermediate contexts do not exist.
0398 *
0399 * <p> Any attributes associated with the name are removed.
0400 * Intermediate contexts are not changed.
0401 *
0402 * @param name
0403 * the name to unbind; may not be empty
0404 * @throws NameNotFoundException if an intermediate context does not exist
0405 * @throws NamingException if a naming exception is encountered
0406 * @see #unbind(String)
0407 */
0408 public void unbind(Name name) throws NamingException;
0409
0410 /**
0411 * Unbinds the named object.
0412 * See {@link #unbind(Name)} for details.
0413 *
0414 * @param name
0415 * the name to unbind; may not be empty
0416 * @throws NameNotFoundException if an intermediate context does not exist
0417 * @throws NamingException if a naming exception is encountered
0418 */
0419 public void unbind(String name) throws NamingException;
0420
0421 /**
0422 * Binds a new name to the object bound to an old name, and unbinds
0423 * the old name. Both names are relative to this context.
0424 * Any attributes associated with the old name become associated
0425 * with the new name.
0426 * Intermediate contexts of the old name are not changed.
0427 *
0428 * @param oldName
0429 * the name of the existing binding; may not be empty
0430 * @param newName
0431 * the name of the new binding; may not be empty
0432 * @throws NameAlreadyBoundException if <tt>newName</tt> is already bound
0433 * @throws NamingException if a naming exception is encountered
0434 *
0435 * @see #rename(String, String)
0436 * @see #bind(Name, Object)
0437 * @see #rebind(Name, Object)
0438 */
0439 public void rename(Name oldName, Name newName)
0440 throws NamingException;
0441
0442 /**
0443 * Binds a new name to the object bound to an old name, and unbinds
0444 * the old name.
0445 * See {@link #rename(Name, Name)} for details.
0446 *
0447 * @param oldName
0448 * the name of the existing binding; may not be empty
0449 * @param newName
0450 * the name of the new binding; may not be empty
0451 * @throws NameAlreadyBoundException if <tt>newName</tt> is already bound
0452 * @throws NamingException if a naming exception is encountered
0453 */
0454 public void rename(String oldName, String newName)
0455 throws NamingException;
0456
0457 /**
0458 * Enumerates the names bound in the named context, along with the
0459 * class names of objects bound to them.
0460 * The contents of any subcontexts are not included.
0461 *
0462 * <p> If a binding is added to or removed from this context,
0463 * its effect on an enumeration previously returned is undefined.
0464 *
0465 * @param name
0466 * the name of the context to list
0467 * @return an enumeration of the names and class names of the
0468 * bindings in this context. Each element of the
0469 * enumeration is of type <tt>NameClassPair</tt>.
0470 * @throws NamingException if a naming exception is encountered
0471 *
0472 * @see #list(String)
0473 * @see #listBindings(Name)
0474 * @see NameClassPair
0475 */
0476 public NamingEnumeration<NameClassPair> list(Name name)
0477 throws NamingException;
0478
0479 /**
0480 * Enumerates the names bound in the named context, along with the
0481 * class names of objects bound to them.
0482 * See {@link #list(Name)} for details.
0483 *
0484 * @param name
0485 * the name of the context to list
0486 * @return an enumeration of the names and class names of the
0487 * bindings in this context. Each element of the
0488 * enumeration is of type <tt>NameClassPair</tt>.
0489 * @throws NamingException if a naming exception is encountered
0490 */
0491 public NamingEnumeration<NameClassPair> list(String name)
0492 throws NamingException;
0493
0494 /**
0495 * Enumerates the names bound in the named context, along with the
0496 * objects bound to them.
0497 * The contents of any subcontexts are not included.
0498 *
0499 * <p> If a binding is added to or removed from this context,
0500 * its effect on an enumeration previously returned is undefined.
0501 *
0502 * @param name
0503 * the name of the context to list
0504 * @return an enumeration of the bindings in this context.
0505 * Each element of the enumeration is of type
0506 * <tt>Binding</tt>.
0507 * @throws NamingException if a naming exception is encountered
0508 *
0509 * @see #listBindings(String)
0510 * @see #list(Name)
0511 * @see Binding
0512 */
0513 public NamingEnumeration<Binding> listBindings(Name name)
0514 throws NamingException;
0515
0516 /**
0517 * Enumerates the names bound in the named context, along with the
0518 * objects bound to them.
0519 * See {@link #listBindings(Name)} for details.
0520 *
0521 * @param name
0522 * the name of the context to list
0523 * @return an enumeration of the bindings in this context.
0524 * Each element of the enumeration is of type
0525 * <tt>Binding</tt>.
0526 * @throws NamingException if a naming exception is encountered
0527 */
0528 public NamingEnumeration<Binding> listBindings(String name)
0529 throws NamingException;
0530
0531 /**
0532 * Destroys the named context and removes it from the namespace.
0533 * Any attributes associated with the name are also removed.
0534 * Intermediate contexts are not destroyed.
0535 *
0536 * <p> This method is idempotent.
0537 * It succeeds even if the terminal atomic name
0538 * is not bound in the target context, but throws
0539 * <tt>NameNotFoundException</tt>
0540 * if any of the intermediate contexts do not exist.
0541 *
0542 * <p> In a federated naming system, a context from one naming system
0543 * may be bound to a name in another. One can subsequently
0544 * look up and perform operations on the foreign context using a
0545 * composite name. However, an attempt destroy the context using
0546 * this composite name will fail with
0547 * <tt>NotContextException</tt>, because the foreign context is not
0548 * a "subcontext" of the context in which it is bound.
0549 * Instead, use <tt>unbind()</tt> to remove the
0550 * binding of the foreign context. Destroying the foreign context
0551 * requires that the <tt>destroySubcontext()</tt> be performed
0552 * on a context from the foreign context's "native" naming system.
0553 *
0554 * @param name
0555 * the name of the context to be destroyed; may not be empty
0556 * @throws NameNotFoundException if an intermediate context does not exist
0557 * @throws NotContextException if the name is bound but does not name a
0558 * context, or does not name a context of the appropriate type
0559 * @throws ContextNotEmptyException if the named context is not empty
0560 * @throws NamingException if a naming exception is encountered
0561 *
0562 * @see #destroySubcontext(String)
0563 */
0564 public void destroySubcontext(Name name) throws NamingException;
0565
0566 /**
0567 * Destroys the named context and removes it from the namespace.
0568 * See {@link #destroySubcontext(Name)} for details.
0569 *
0570 * @param name
0571 * the name of the context to be destroyed; may not be empty
0572 * @throws NameNotFoundException if an intermediate context does not exist
0573 * @throws NotContextException if the name is bound but does not name a
0574 * context, or does not name a context of the appropriate type
0575 * @throws ContextNotEmptyException if the named context is not empty
0576 * @throws NamingException if a naming exception is encountered
0577 */
0578 public void destroySubcontext(String name) throws NamingException;
0579
0580 /**
0581 * Creates and binds a new context.
0582 * Creates a new context with the given name and binds it in
0583 * the target context (that named by all but terminal atomic
0584 * component of the name). All intermediate contexts and the
0585 * target context must already exist.
0586 *
0587 * @param name
0588 * the name of the context to create; may not be empty
0589 * @return the newly created context
0590 *
0591 * @throws NameAlreadyBoundException if name is already bound
0592 * @throws javax.naming.directory.InvalidAttributesException
0593 * if creation of the subcontext requires specification of
0594 * mandatory attributes
0595 * @throws NamingException if a naming exception is encountered
0596 *
0597 * @see #createSubcontext(String)
0598 * @see javax.naming.directory.DirContext#createSubcontext
0599 */
0600 public Context createSubcontext(Name name) throws NamingException;
0601
0602 /**
0603 * Creates and binds a new context.
0604 * See {@link #createSubcontext(Name)} for details.
0605 *
0606 * @param name
0607 * the name of the context to create; may not be empty
0608 * @return the newly created context
0609 *
0610 * @throws NameAlreadyBoundException if name is already bound
0611 * @throws javax.naming.directory.InvalidAttributesException
0612 * if creation of the subcontext requires specification of
0613 * mandatory attributes
0614 * @throws NamingException if a naming exception is encountered
0615 */
0616 public Context createSubcontext(String name) throws NamingException;
0617
0618 /**
0619 * Retrieves the named object, following links except
0620 * for the terminal atomic component of the name.
0621 * If the object bound to <tt>name</tt> is not a link,
0622 * returns the object itself.
0623 *
0624 * @param name
0625 * the name of the object to look up
0626 * @return the object bound to <tt>name</tt>, not following the
0627 * terminal link (if any).
0628 * @throws NamingException if a naming exception is encountered
0629 *
0630 * @see #lookupLink(String)
0631 */
0632 public Object lookupLink(Name name) throws NamingException;
0633
0634 /**
0635 * Retrieves the named object, following links except
0636 * for the terminal atomic component of the name.
0637 * See {@link #lookupLink(Name)} for details.
0638 *
0639 * @param name
0640 * the name of the object to look up
0641 * @return the object bound to <tt>name</tt>, not following the
0642 * terminal link (if any)
0643 * @throws NamingException if a naming exception is encountered
0644 */
0645 public Object lookupLink(String name) throws NamingException;
0646
0647 /**
0648 * Retrieves the parser associated with the named context.
0649 * In a federation of namespaces, different naming systems will
0650 * parse names differently. This method allows an application
0651 * to get a parser for parsing names into their atomic components
0652 * using the naming convention of a particular naming system.
0653 * Within any single naming system, <tt>NameParser</tt> objects
0654 * returned by this method must be equal (using the <tt>equals()</tt>
0655 * test).
0656 *
0657 * @param name
0658 * the name of the context from which to get the parser
0659 * @return a name parser that can parse compound names into their atomic
0660 * components
0661 * @throws NamingException if a naming exception is encountered
0662 *
0663 * @see #getNameParser(String)
0664 * @see CompoundName
0665 */
0666 public NameParser getNameParser(Name name) throws NamingException;
0667
0668 /**
0669 * Retrieves the parser associated with the named context.
0670 * See {@link #getNameParser(Name)} for details.
0671 *
0672 * @param name
0673 * the name of the context from which to get the parser
0674 * @return a name parser that can parse compound names into their atomic
0675 * components
0676 * @throws NamingException if a naming exception is encountered
0677 */
0678 public NameParser getNameParser(String name) throws NamingException;
0679
0680 /**
0681 * Composes the name of this context with a name relative to
0682 * this context.
0683 * Given a name (<code>name</code>) relative to this context, and
0684 * the name (<code>prefix</code>) of this context relative to one
0685 * of its ancestors, this method returns the composition of the
0686 * two names using the syntax appropriate for the naming
0687 * system(s) involved. That is, if <code>name</code> names an
0688 * object relative to this context, the result is the name of the
0689 * same object, but relative to the ancestor context. None of the
0690 * names may be null.
0691 * <p>
0692 * For example, if this context is named "wiz.com" relative
0693 * to the initial context, then
0694 * <pre>
0695 * composeName("east", "wiz.com") </pre>
0696 * might return <code>"east.wiz.com"</code>.
0697 * If instead this context is named "org/research", then
0698 * <pre>
0699 * composeName("user/jane", "org/research") </pre>
0700 * might return <code>"org/research/user/jane"</code> while
0701 * <pre>
0702 * composeName("user/jane", "research") </pre>
0703 * returns <code>"research/user/jane"</code>.
0704 *
0705 * @param name
0706 * a name relative to this context
0707 * @param prefix
0708 * the name of this context relative to one of its ancestors
0709 * @return the composition of <code>prefix</code> and <code>name</code>
0710 * @throws NamingException if a naming exception is encountered
0711 *
0712 * @see #composeName(String, String)
0713 */
0714 public Name composeName(Name name, Name prefix)
0715 throws NamingException;
0716
0717 /**
0718 * Composes the name of this context with a name relative to
0719 * this context.
0720 * See {@link #composeName(Name, Name)} for details.
0721 *
0722 * @param name
0723 * a name relative to this context
0724 * @param prefix
0725 * the name of this context relative to one of its ancestors
0726 * @return the composition of <code>prefix</code> and <code>name</code>
0727 * @throws NamingException if a naming exception is encountered
0728 */
0729 public String composeName(String name, String prefix)
0730 throws NamingException;
0731
0732 /**
0733 * Adds a new environment property to the environment of this
0734 * context. If the property already exists, its value is overwritten.
0735 * See class description for more details on environment properties.
0736 *
0737 * @param propName
0738 * the name of the environment property to add; may not be null
0739 * @param propVal
0740 * the value of the property to add; may not be null
0741 * @return the previous value of the property, or null if the property was
0742 * not in the environment before
0743 * @throws NamingException if a naming exception is encountered
0744 *
0745 * @see #getEnvironment()
0746 * @see #removeFromEnvironment(String)
0747 */
0748 public Object addToEnvironment(String propName, Object propVal)
0749 throws NamingException;
0750
0751 /**
0752 * Removes an environment property from the environment of this
0753 * context. See class description for more details on environment
0754 * properties.
0755 *
0756 * @param propName
0757 * the name of the environment property to remove; may not be null
0758 * @return the previous value of the property, or null if the property was
0759 * not in the environment
0760 * @throws NamingException if a naming exception is encountered
0761 *
0762 * @see #getEnvironment()
0763 * @see #addToEnvironment(String, Object)
0764 */
0765 public Object removeFromEnvironment(String propName)
0766 throws NamingException;
0767
0768 /**
0769 * Retrieves the environment in effect for this context.
0770 * See class description for more details on environment properties.
0771 *
0772 * <p> The caller should not make any changes to the object returned:
0773 * their effect on the context is undefined.
0774 * The environment of this context may be changed using
0775 * <tt>addToEnvironment()</tt> and <tt>removeFromEnvironment()</tt>.
0776 *
0777 * @return the environment of this context; never null
0778 * @throws NamingException if a naming exception is encountered
0779 *
0780 * @see #addToEnvironment(String, Object)
0781 * @see #removeFromEnvironment(String)
0782 */
0783 public Hashtable<?, ?> getEnvironment() throws NamingException;
0784
0785 /**
0786 * Closes this context.
0787 * This method releases this context's resources immediately, instead of
0788 * waiting for them to be released automatically by the garbage collector.
0789 *
0790 * <p> This method is idempotent: invoking it on a context that has
0791 * already been closed has no effect. Invoking any other method
0792 * on a closed context is not allowed, and results in undefined behaviour.
0793 *
0794 * @throws NamingException if a naming exception is encountered
0795 */
0796 public void close() throws NamingException;
0797
0798 /**
0799 * Retrieves the full name of this context within its own namespace.
0800 *
0801 * <p> Many naming services have a notion of a "full name" for objects
0802 * in their respective namespaces. For example, an LDAP entry has
0803 * a distinguished name, and a DNS record has a fully qualified name.
0804 * This method allows the client application to retrieve this name.
0805 * The string returned by this method is not a JNDI composite name
0806 * and should not be passed directly to context methods.
0807 * In naming systems for which the notion of full name does not
0808 * make sense, <tt>OperationNotSupportedException</tt> is thrown.
0809 *
0810 * @return this context's name in its own namespace; never null
0811 * @throws OperationNotSupportedException if the naming system does
0812 * not have the notion of a full name
0813 * @throws NamingException if a naming exception is encountered
0814 *
0815 * @since 1.3
0816 */
0817 public String getNameInNamespace() throws NamingException;
0818
0819 // public static final: JLS says recommended style is to omit these modifiers
0820 // because they are the default
0821
0822 /**
0823 * Constant that holds the name of the environment property
0824 * for specifying the initial context factory to use. The value
0825 * of the property should be the fully qualified class name
0826 * of the factory class that will create an initial context.
0827 * This property may be specified in the environment parameter
0828 * passed to the initial context constructor, an applet parameter,
0829 * a system property, or an application resource file.
0830 * If it is not specified in any of these sources,
0831 * <tt>NoInitialContextException</tt> is thrown when an initial
0832 * context is required to complete an operation.
0833 *
0834 * <p> The value of this constant is "java.naming.factory.initial".
0835 *
0836 * @see InitialContext
0837 * @see javax.naming.directory.InitialDirContext
0838 * @see javax.naming.spi.NamingManager#getInitialContext
0839 * @see javax.naming.spi.InitialContextFactory
0840 * @see NoInitialContextException
0841 * @see #addToEnvironment(String, Object)
0842 * @see #removeFromEnvironment(String)
0843 * @see #APPLET
0844 */
0845 String INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial";
0846
0847 /**
0848 * Constant that holds the name of the environment property
0849 * for specifying the list of object factories to use. The value
0850 * of the property should be a colon-separated list of the fully
0851 * qualified class names of factory classes that will create an object
0852 * given information about the object.
0853 * This property may be specified in the environment, an applet
0854 * parameter, a system property, or one or more resource files.
0855 *
0856 * <p> The value of this constant is "java.naming.factory.object".
0857 *
0858 * @see javax.naming.spi.NamingManager#getObjectInstance
0859 * @see javax.naming.spi.ObjectFactory
0860 * @see #addToEnvironment(String, Object)
0861 * @see #removeFromEnvironment(String)
0862 * @see #APPLET
0863 */
0864 String OBJECT_FACTORIES = "java.naming.factory.object";
0865
0866 /**
0867 * Constant that holds the name of the environment property
0868 * for specifying the list of state factories to use. The value
0869 * of the property should be a colon-separated list of the fully
0870 * qualified class names of state factory classes that will be used
0871 * to get an object's state given the object itself.
0872 * This property may be specified in the environment, an applet
0873 * parameter, a system property, or one or more resource files.
0874 *
0875 * <p> The value of this constant is "java.naming.factory.state".
0876 *
0877 * @see javax.naming.spi.NamingManager#getStateToBind
0878 * @see javax.naming.spi.StateFactory
0879 * @see #addToEnvironment(String, Object)
0880 * @see #removeFromEnvironment(String)
0881 * @see #APPLET
0882 * @since 1.3
0883 */
0884 String STATE_FACTORIES = "java.naming.factory.state";
0885
0886 /**
0887 * Constant that holds the name of the environment property
0888 * for specifying the list of package prefixes to use when
0889 * loading in URL context factories. The value
0890 * of the property should be a colon-separated list of package
0891 * prefixes for the class name of the factory class that will create
0892 * a URL context factory.
0893 * This property may be specified in the environment,
0894 * an applet parameter, a system property, or one or more
0895 * resource files.
0896 * The prefix <tt>com.sun.jndi.url</tt> is always appended to
0897 * the possibly empty list of package prefixes.
0898 *
0899 * <p> The value of this constant is "java.naming.factory.url.pkgs".
0900 *
0901 * @see javax.naming.spi.NamingManager#getObjectInstance
0902 * @see javax.naming.spi.NamingManager#getURLContext
0903 * @see javax.naming.spi.ObjectFactory
0904 * @see #addToEnvironment(String, Object)
0905 * @see #removeFromEnvironment(String)
0906 * @see #APPLET
0907 */
0908 String URL_PKG_PREFIXES = "java.naming.factory.url.pkgs";
0909
0910 /**
0911 * Constant that holds the name of the environment property
0912 * for specifying configuration information for the service provider
0913 * to use. The value of the property should contain a URL string
0914 * (e.g. "ldap://somehost:389").
0915 * This property may be specified in the environment,
0916 * an applet parameter, a system property, or a resource file.
0917 * If it is not specified in any of these sources,
0918 * the default configuration is determined by the service provider.
0919 *
0920 * <p> The value of this constant is "java.naming.provider.url".
0921 *
0922 * @see #addToEnvironment(String, Object)
0923 * @see #removeFromEnvironment(String)
0924 * @see #APPLET
0925 */
0926 String PROVIDER_URL = "java.naming.provider.url";
0927
0928 /**
0929 * Constant that holds the name of the environment property
0930 * for specifying the DNS host and domain names to use for the
0931 * JNDI URL context (for example, "dns://somehost/wiz.com").
0932 * This property may be specified in the environment,
0933 * an applet parameter, a system property, or a resource file.
0934 * If it is not specified in any of these sources
0935 * and the program attempts to use a JNDI URL containing a DNS name,
0936 * a <tt>ConfigurationException</tt> will be thrown.
0937 *
0938 * <p> The value of this constant is "java.naming.dns.url".
0939 *
0940 * @see #addToEnvironment(String, Object)
0941 * @see #removeFromEnvironment(String)
0942 */
0943 String DNS_URL = "java.naming.dns.url";
0944
0945 /**
0946 * Constant that holds the name of the environment property for
0947 * specifying the authoritativeness of the service requested.
0948 * If the value of the property is the string "true", it means
0949 * that the access is to the most authoritative source (i.e. bypass
0950 * any cache or replicas). If the value is anything else,
0951 * the source need not be (but may be) authoritative.
0952 * If unspecified, the value defaults to "false".
0953 *
0954 * <p> The value of this constant is "java.naming.authoritative".
0955 *
0956 * @see #addToEnvironment(String, Object)
0957 * @see #removeFromEnvironment(String)
0958 */
0959 String AUTHORITATIVE = "java.naming.authoritative";
0960
0961 /**
0962 * Constant that holds the name of the environment property for
0963 * specifying the batch size to use when returning data via the
0964 * service's protocol. This is a hint to the provider to return
0965 * the results of operations in batches of the specified size, so
0966 * the provider can optimize its performance and usage of resources.
0967 * The value of the property is the string representation of an
0968 * integer.
0969 * If unspecified, the batch size is determined by the service
0970 * provider.
0971 *
0972 * <p> The value of this constant is "java.naming.batchsize".
0973 *
0974 * @see #addToEnvironment(String, Object)
0975 * @see #removeFromEnvironment(String)
0976 */
0977 String BATCHSIZE = "java.naming.batchsize";
0978
0979 /**
0980 * Constant that holds the name of the environment property for
0981 * specifying how referrals encountered by the service provider
0982 * are to be processed. The value of the property is one of the
0983 * following strings:
0984 * <dl>
0985 * <dt>"follow"
0986 * <dd>follow referrals automatically
0987 * <dt>"ignore"
0988 * <dd>ignore referrals
0989 * <dt>"throw"
0990 * <dd>throw <tt>ReferralException</tt> when a referral is encountered.
0991 * </dl>
0992 * If this property is not specified, the default is
0993 * determined by the provider.
0994 *
0995 * <p> The value of this constant is "java.naming.referral".
0996 *
0997 * @see #addToEnvironment(String, Object)
0998 * @see #removeFromEnvironment(String)
0999 */
1000 String REFERRAL = "java.naming.referral";
1001
1002 /**
1003 * Constant that holds the name of the environment property for
1004 * specifying the security protocol to use.
1005 * Its value is a string determined by the service provider
1006 * (e.g. "ssl").
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.protocol".
1011 *
1012 * @see #addToEnvironment(String, Object)
1013 * @see #removeFromEnvironment(String)
1014 */
1015 String SECURITY_PROTOCOL = "java.naming.security.protocol";
1016
1017 /**
1018 * Constant that holds the name of the environment property for
1019 * specifying the security level to use.
1020 * Its value is one of the following strings:
1021 * "none", "simple", "strong".
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.authentication".
1026 *
1027 * @see #addToEnvironment(String, Object)
1028 * @see #removeFromEnvironment(String)
1029 */
1030 String SECURITY_AUTHENTICATION = "java.naming.security.authentication";
1031
1032 /**
1033 * Constant that holds the name of the environment property for
1034 * specifying the identity of the principal for authenticating
1035 * the caller to the service. The format of the principal
1036 * depends on the authentication scheme.
1037 * If this property is unspecified,
1038 * the behaviour is determined by the service provider.
1039 *
1040 * <p> The value of this constant is "java.naming.security.principal".
1041 *
1042 * @see #addToEnvironment(String, Object)
1043 * @see #removeFromEnvironment(String)
1044 */
1045 String SECURITY_PRINCIPAL = "java.naming.security.principal";
1046
1047 /**
1048 * Constant that holds the name of the environment property for
1049 * specifying the credentials of the principal for authenticating
1050 * the caller to the service. The value of the property depends
1051 * on the authentication scheme. For example, it could be a hashed
1052 * password, clear-text password, key, certificate, and so on.
1053 * If this property is unspecified,
1054 * the behaviour is determined by the service provider.
1055 *
1056 * <p> The value of this constant is "java.naming.security.credentials".
1057 *
1058 * @see #addToEnvironment(String, Object)
1059 * @see #removeFromEnvironment(String)
1060 */
1061
1062 String SECURITY_CREDENTIALS = "java.naming.security.credentials";
1063 /**
1064 * Constant that holds the name of the environment property for
1065 * specifying the preferred language to use with the service.
1066 * The value of the property is a colon-separated list of language
1067 * tags as defined in RFC 1766.
1068 * If this property is unspecified,
1069 * the language preference is determined by the service provider.
1070 *
1071 * <p> The value of this constant is "java.naming.language".
1072 *
1073 * @see #addToEnvironment(String, Object)
1074 * @see #removeFromEnvironment(String)
1075 */
1076 String LANGUAGE = "java.naming.language";
1077
1078 /**
1079 * Constant that holds the name of the environment property for
1080 * specifying an applet for the initial context constructor to use
1081 * when searching for other properties.
1082 * The value of this property is the
1083 * <tt>java.applet.Applet</tt> instance that is being executed.
1084 * This property may be specified in the environment parameter
1085 * passed to the initial context constructor.
1086 * When this property is set, each property that the initial context
1087 * constructor looks for in the system properties is first looked for
1088 * in the applet's parameter list.
1089 * If this property is unspecified, the initial context constructor
1090 * will search for properties only in the environment parameter
1091 * passed to it, the system properties, and application resource files.
1092 *
1093 * <p> The value of this constant is "java.naming.applet".
1094 *
1095 * @see #addToEnvironment(String, Object)
1096 * @see #removeFromEnvironment(String)
1097 * @see InitialContext
1098 *
1099 * @since 1.3
1100 */
1101 String APPLET = "java.naming.applet";
1102 };
|