javax.naming.Context

javax.naming.Context is a context interface for connection configuration.

Description

javax.naming.Context consists of a set of name-to-object bindings, and contains methods for examining and updating these bindings.

Names

Each name passed as a parameter to the Context method is related to the context. An empty name is used to name the context itself. A name parameter cannot be null.

Most of the methods have overloaded versions, for example, a method that uses a Name parameter and a method that usesa String. These overloaded versions are equivalent. If the Name and String parameters are just different representations of the same name, the overloaded versions of the same methods exhibit same behaviors.

Exceptions

All methods in this interface can throw a NamingException or any exceptions of the subclasses of NamingException.

Concurrent access

It cannot be guaranteed that a Context is synchronous with concurrent access of multiple threads. For threads that need to access a single Context instance concurrently, synchronization must be implemented between these threads and necessary locking needs to be provided. Synchronization is not required among multiple threads that each operate on a different Context instance. Note that when an empty name is passed, the lookup method will return a new Context instance that represents the same naming context.

To achieve concurrency control, a Context operation that returns a NamingEnumeration is considered uncompleted if the enumeration is still in use or any referrals generated by the operation are still in use.

Parameters

The service provider will not modify the Name parameter passed to a method of the Context interface or a method of its subinterfaces. The service provider may keep a reference to the Name parameter during operations, for example, during the enumeration of the method results and the processing of any referrals generated. The caller must not modify the object defined by the Name parameter during this period. A Name returned by any such method is owned by the caller. The name may be subsequently modified by the caller, but not by the service provider.

Environment properties

Java Naming and Directory Interface (JNDI) applications require methods for transferring various preferences and attributes. These preferences and attributes define an environment for accessing naming and directory services. For example, security credentials may need to be specified for a context for accessing services. In another method, an environment of a context is used to provide server configuration information. The Context interface provides methods for retrieving and updating this environment.

The environment is inherited from the parent context when a context method proceeds from one context to the next. Changes to the environment of one context do not directly affect those of other contexts.

The use and validity verification of environment properties depend on the implementation. For example, the service provider uses some security-related properties to "log on" to the directory. This logon process may occur when the context is created or when the first time a method is invoked on the context. When and whether this occurs depends on the implementation. When environment properties are added to or removed from a context, verification of the validity of the changes also depends on the implementation. For example, verification of some properties may occur when a change is made or when the next operation is performed on the context, or property verification will not be performed

Any object with a reference to a context may examine the environment of the context. Do not store sensitive information such as plain-text passwords in a context unless protection measures are unavailable.

Resource files

To simplify the process for setting up the environment required by a JNDI application, the application components and service providers may be distributed along with resource files. A JNDI resource file is a file in the properties file format and contains a list of key/value pairs. A key is the name of a property, and a value is a string in the format defined for the property.

The JNDI class library reads the resource files and makes the property values available. There are two kinds of JNDI resource files: provider resource files and application resource files.

Provider resource files

Each service provider has an optional resource that lists properties specific to this provider. The name of this resource is in the following format:

[prefix/]jndiprovider.properties

prefix is the package name of the context implementation of the provider, with each period (".") converted to a slash ("/").

The following methods in the JNDI class library use 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

When the JNDI library determines the values of these properties, it will refer to the provider resource file. The documentation of the service provider must clearly state the properties allowed. Then, other properties in the file will be ignored.

Application resource files

When an application is deployed, the classpath of the application usually contain multiple codebase directories and JAR packages. JNDI locates all application resource files named jndi.properties in the classpath by using ClassLoader.getResources(). In addition, if the Java installation directory contains a built-in property file, for example, conf/jndi.properties, JNDI treats it as an additional application resource file. All of the properties contained in these files are placed into the environment of the initial context. This environment may be then inherited by other contexts.

For a property that can found in more than one application resource file, JNDI uses the first value found, or concatenates all of the values in some cases. 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 these three files. JNDI automatically collects and uses all of these export lists when it searches for factory classes.

Search algorithm for properties

When JNDI constructs an initial context, the environment of the context is initialized by using properties defined in the environment parameter that is passed to the constructor and using the system properties and the application resource files. This initial environment can be subsequently inherited by other context instances.

When the JNDI class library needs to determine the value of a property, it merges 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 a property found in both of these two sources, JNDI determines the property value in the following manner:

• If the property is one of the standard JNDI properties that specify a list of JNDI factories, the values are concatenated into a single colon-separated list.

• Otherwise, only the first value found is used.

When a service provider needs to determine the value of a property, it will generally obtain the value directly from the environment. A service provider may define provider-specific properties and place them in its own provider resource file. In that case, it should merge values. In this way, the developer of each service provider can specify a list of factories that the service provider can use. The list of factories can be modified by the application resources specified by the deployer of the application, and the resources in turn can be modified by the user.

Methods