JNDI Concepts

Internal

• JNDI

Context

A JNDI context consists of name-to-object bindings.

* This interface represents a naming context, which
* consists of a set of name-to-object bindings.
* It contains methods for examining and updating these bindings.
*

*

Names

* Each name passed as an argument to a Context method is relative
* to that context.  The empty name is used to name the context itself.
* A name parameter may never be null.

*

* Most of the methods have overloaded versions with one taking a * Name parameter and one taking a String. * These overloaded versions are equivalent in that if * the Name and String parameters are just * different representations of the same name, then the overloaded * versions of the same methods behave the same. * In the method descriptions below, only one version is fully documented. * The second version instead has a link to the first: the same * documentation applies to both. *

* For systems that support federation, String name arguments to * Context methods are composite names. Name arguments that are * instances of CompositeName are treated as composite names, * while Name arguments that are not instances of * CompositeName are treated as compound names (which might be * instances of CompoundName or other implementations of compound * names). This allows the results of NameParser.parse() to be used as * arguments to the Context methods. * Prior to JNDI 1.2, all name arguments were treated as composite names. *

* Furthermore, for systems that support federation, all names returned * in a NamingEnumeration * from list() and listBindings() are composite names * represented as strings. * See CompositeName for the string syntax of names. *

* For systems that do not support federation, the name arguments (in * either Name or String forms) and the names returned in * NamingEnumeration may be names in their own namespace rather than * names in a composite namespace, at the discretion of the service * provider. * *

Exceptions

* All the methods in this interface can throw a NamingException or
* any of its subclasses. See NamingException and their subclasses
* for details on each exception.
*

*

Concurrent Access

* A Context instance is not guaranteed to be synchronized against
* concurrent access by multiple threads.  Threads that need to access
* a single Context instance concurrently should synchronize amongst
* themselves and provide the necessary locking.  Multiple threads
* each manipulating a different Context instance need not
* synchronize.  Note that the {@link #lookup(Name) lookup}
* method, when passed an empty name, will return a new Context instance
* representing the same naming context.

*

* For purposes of concurrency control, * a Context operation that returns a NamingEnumeration is * not considered to have completed while the enumeration is still in * use, or while any referrals generated by that operation are still * being followed. * * *

Parameters

* A Name parameter passed to any method of the
* Context interface or one of its subinterfaces
* will not be modified by the service provider.
* The service provider may keep a reference to it
* for the duration of the operation, including any enumeration of the
* method's results and the processing of any referrals generated.
* The caller should not modify the object during this time.
* A Name returned by any such method is owned by the caller.
* The caller may subsequently modify it; the service provider may not.
*
*

*

Environment Properties

*

* JNDI applications need a way to communicate various preferences * and properties that define the environment in which naming and * directory services are accessed. For example, a context might * require specification of security credentials in order to access * the service. Another context might require that server configuration * information be supplied. These are referred to as the environment * of a context. The Context interface provides methods for * retrieving and updating this environment. *

* The environment is inherited from the parent context as * context methods proceed from one context to the next. Changes to * the environment of one context do not directly affect those * of other contexts. *

* It is implementation-dependent when environment properties are used * and/or verified for validity. For example, some of the * security-related properties are used by service providers to "log in" * to the directory. This login process might occur at the time the * context is created, or the first time a method is invoked on the * context. When, and whether this occurs at all, is * implementation-dependent. When environment properties are added or * removed from the context, verifying the validity of the changes is again * implementation-dependent. For example, verification of some properties * might occur at the time the change is made, or at the time the next * operation is performed on the context, or not at all. *

* Any object with a reference to a context may examine that context's * environment. Sensitive information such as clear-text * passwords should not be stored there unless the implementation is * known to protect it. * *

*<a name=RESOURCEFILES></a> *

Resource Files

*

* To simplify the task of setting up the environment * required by a JNDI application, * application components and service providers may be distributed * along with resource files. * A JNDI resource file is a file in the properties file format (see * {@link java.util.Properties#load java.util.Properties}), * containing a list of key/value pairs. * The key is the name of the property (e.g. "java.naming.factory.object") * and the value is a string in the format defined * for that property. Here is an example of a JNDI resource file: * *

{@code

* java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person * java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person * java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory

* }

*
* The JNDI class library reads the resource files and makes the property
* values freely available.  Thus JNDI resource files should be considered
* to be "world readable", and sensitive information such as clear-text
* passwords should not be stored there.

*

* There are two kinds of JNDI resource files: * provider and application. * *

Provider Resource Files

*
* Each service provider has an optional resource that lists properties
* specific to that provider.  The name of this resource is:

*

* [prefix/]jndiprovider.properties

*

* where prefix is
* the package name of the provider's context implementation(s),
* with each period (".") converted to a slash ("/").
*
* For example, suppose a service provider defines a context
* implementation with class name com.sun.jndi.ldap.LdapCtx.
* The provider resource for this provider is named
* com/sun/jndi/ldap/jndiprovider.properties.  If the class is
* not in a package, the resource's name is simply
* jndiprovider.properties.
*

*

* <a name=LISTPROPS></a> * Certain methods in the JNDI class library make use of the standard * JNDI properties that specify lists of JNDI factories: *

*
• java.naming.factory.object *
• java.naming.factory.state *
• java.naming.factory.control *
• java.naming.factory.url.pkgs *

* The JNDI library will consult the provider resource file
* when determining the values of these properties.
* Properties other than these may be set in the provider
* resource file at the discretion of the service provider.
* The service provider's documentation should clearly state which
* properties are allowed; other properties in the file will be ignored.
*

*

Application Resource Files

*
* When an application is deployed, it will generally have several
* codebase directories and JARs in its classpath.  Similarly, when an
* applet is deployed, it will have a codebase and archives specifying
* where to find the applet's classes.  JNDI locates (using
* {@link ClassLoader#getResources ClassLoader.getResources()})
* all application resource files named jndi.properties
* in the classpath.
* In addition, if the file java.home/lib/jndi.properties
* exists and is readable,
* JNDI treats it as an additional application resource file.
* (java.home indicates the
* directory named by the java.home system property.)
* All of the properties contained in these files are placed
* into the environment of the initial context.  This environment
* is then inherited by other contexts.
*

*

* For each property found in more than one application resource file, * JNDI uses the first value found or, in a few cases where it makes * sense to do so, it concatenates all of the values (details are given * below). * For example, if the "java.naming.factory.object" property is found in * three jndi.properties resource files, the * list of object factories is a concatenation of the property * values from all three files. * Using this scheme, each deployable component is responsible for * listing the factories that it exports. JNDI automatically * collects and uses all of these export lists when searching for factory * classes. * *

Search Algorithm for Properties

*
* When JNDI constructs an initial context, the context's environment
* is initialized with properties defined in the environment parameter
* passed to the constructor, the system properties, the applet parameters,
* and the application resource files.  See
* <a href=InitialContext.html#ENVIRONMENT>InitialContext</a>
* for details.
* This initial environment is then inherited by other context instances.
*

*

* When the JNDI class library needs to determine * the value of a property, it does so by merging * the values from the following two sources, in order: *

*
1. The environment of the context being operated on. *
2. The provider resource file (jndiprovider.properties) * for the context being operated on. *

* For each property found in both of these two sources,
* JNDI determines the property's value as follows.  If the property is
* one of the standard JNDI properties that specify a list of JNDI
* factories (listed <a href=#LISTPROPS>above</a>), the values are
* concatenated into a single colon-separated list.  For other
* properties, only the first value found is used.
*

*

* When a service provider needs to determine the value of a property, * it will generally take that value directly from the environment. * A service provider may define provider-specific properties * to be placed in its own provider resource file. In that * case it should merge values as described in the previous paragraph. * *

* In this way, each service provider developer can specify a list of * factories to use with that service provider. These can be modified by * the application resources specified by the deployer of the application * or applet, which in turn can be modified by the user. * * @author Rosanna Lee * @author Scott Seligman * @author R. Vasudevan * * @since 1.3

NameClassPair

The javax.naming.NameClassPair class represents the name and the class of an object bound in JNDI into a specific context. The name is the , and the class is represented by a fully qualified class name.