Java Doc for Context.java in  » Apache-Harmony-Java-SE » javax-package » javax » naming » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Any of the methods may throw a NamingException or one of its subclasses. The specifications for those exceptions explain the circumstances in which they may be thrown.

Name parameters to context methods are each relative to the context. Name parameters cannot be null. The empty name, whether of type Name or String, is the name of the initial context. Names may be composed of multiple components; for example, in the filesystem name "usr/include/stdio.h", each of the components "usr", "include", "stdio.h" is an atomic component, but only "stdio.h" is the terminal atomic component. The example name may be used in context operations providing the intervening parent contexts for "usr" and "include" already exist. Finally, if the current context has name "usr/include", then the example name could be the result of composeName("stdio.h","usr/include").

Depending on whether a naming system supports federation, that is, names that may include components from different naming systems, name parameters to context methods may be considered differently as described below.

In systems supporting federation, String name parameters are treated as composite names. When Name parameters are not instances of CompositeName, they are deemed to be compound names (CompoundName instances or subclasses of them). Also, when using list() or listBindings() to obtain a NamingEnumeration, all names in the enumeration are string representations of composite names.

Where systems do not support federation, a service provider may treat name parameters to context methods and names found using NamingEnumeration may either as composite names or as compound names. See service provider documentation for details.

Any Name parameter specified to a context method is owned by the caller and will remain unchanged, but applications should avoid modifying these Name objects while the operation has not completed. Any Name object returned by a context operation becomes owned by the caller.

JNDI applications can provide preferences and configuration information, such as security details for authentication to a service, using JNDI environment properties. JNDI environment properties nearly all begin with "java.naming." except for provider-specific properties (explained below). All specified JNDI environment properties together comprise the context environment and methods are available for examining and manipulating that environment. The environment of a context may not necessarily contain all possible JNDI properties; for example, one or more may remain unspecified.

The set of standard JNDI environment properties is:

 Property name                       Value type    Notes
 -------------                       ----------    -----
 java.naming.applet                  F
 java.naming.authoritative           F
 java.naming.batchsize               F
 java.naming.dns.url                 F
 java.naming.factory.control         C             see LdapContext
 java.naming.factory.initial         F
 java.naming.factory.object          C
 java.naming.factory.state           C
 java.naming.factory.url.pkgs        C
 java.naming.language                F
 java.naming.provider.url            F
 java.naming.referral                F
 java.naming.security.authentication F
 java.naming.security.credentials    F
 java.naming.security.principal      F
 java.naming.security.protocol       F
 

For each property above marked with "C" for "concatenate", when encountered while searching sources of environment properties, values are combined into a single list separated by colons and becomes the resulting value of that property.

For each property above marked with "F" for "first occurrence", when encountered while searching sources of environment properties, the first value encountered is the resulting value of that property. In the latter case, and with additional JNDI environment properties explained further below, the type and syntax of acceptable property values should be described in the corresponding documentation for the property. In particular, a property may accept a value consisting of several pieces of relevant information, but the search order and precedence for environment properties ensures that the entire value of the first occurrence of a given property is deemed the value to be used.

Additional JNDI environment properties may be defined according to the needs of the particular service and/or service providers and a few guidelines should be followed when choosing appropriate names for them. Such additional properties comprise service-specific, feature-specific, or provider-specific properties.

Service-specific JNDI properties may be used by all service providers that offer implementations for a given service and would include the service type in the property name prefix. For example, JNDI service providers for Java RMI should name their service-specific JNDI properties using prefix "java.naming.rmi.", or LDAP service providers should use prefix "java.naming.ldap.".

Feature-specific JNDI properties may be used by all service providers offering implementations using a particular flavor of a feature and would include the feature name and the particular flavor name in the property name prefix. A common example is SASL used by several service providers for security; appropriate SASL feature-specific properties would use prefix "java.naming.security.sasl.".

Provider-specific JNDI properties are used by only a single provider though a provider may offer more than one service provider implementation. The provider should ensure uniqueness of their provider properties, for example, an LDAP service provider from mycom might use a service provider package name such as "com.mycom.jndi.ldap." as their provider-specific prefix.

JNDI environment properties can be specified in a Hashtable and passed as the environment parameter when creating an initial context.

Two other important sources of JNDI environment properties are resource files provided by applications and applet parameters (each is considered as an application resource file) and by service provider implementations (provider resource files) in the format of Java properties files - see java.util.Properties class for details.

At runtime, the application classpath and, where appropriate, the applet codebase attribute is used to locate the classes to run; when creating the first initial context, the JNDI also searches the same path for all files (application resource files) called "jndi.properties"; it is the classpath associated with the context ClassLoader (for example, the return value from Thread.getContextClassLoader() or from ClassLoader.getSystemClassLoader()) which is searched to get the resource files. Further, a path comprising the value of the "java.home" system property followed by "lib/jndi.properties" is checked for a readable file; if one exists, then that file is used as another application resource file. All application resource files found in the application classpath are examined, but JNDI properties set in a file found early will override the same properties also set in a file found later in the classpath.

Provider resource files are located according to the package prefix for the service provider's initial context factory and context implementation class in which dot separator characters are converted into slash path separator characters to construct a filepath appended with "jndiprovider.properties". Consider the example where you have a service provider which supplies a context org.apache.harmony.jndi.example.exampleCtx. In this case the package prefix is org.apache.harmony.jndi.example. Substituting slash chars for dots & appending "jndiprovider.properties" gives you org/apache/harmony/jndi/example/jndiprovider.properties.

An important part of service provider implementation is to specify certain standard JNDI properties that are using to locate any of the various factory classes needed for the implementation; these are:

 java.naming.factory.control
 java.naming.factory.object
 java.naming.factory.state
 java.naming.factory.url.pkgs - package prefixes used for URL contexts
 

When searching for the above 4 properties only provider resource files should be examined. Although other properties may be specified in them for use by the service provider implementation, the JNDI ignores properties from these files other than those related to factories.

It should be noted that a provider resource file's properties differ from those in application resource files in that their values are not incorporated into the environment. Instead, they are read when the following methods are invoked with Context and Hashtable parameters:

 ControlFactory.getControlInstance    - uses java.naming.factory.control
 DirectoryManager.getObjectInstance   - uses java.naming.factory.object
 DirectoryManager.getStateToBind      - uses java.naming.factory.state
 NamingManager.getObjectInstance      - uses java.naming.factory.object
 NamingManager.getStateToBind         - uses java.naming.factory.state
 

These methods use their Hashtable parameter to get the environment properties. Then they use the class loader of the Context parameter to look for the provider resource file. If the file is found, then the value of the required property is appended to the value of the required property in the environment. Note that it is appended for use by this method but the environment itself is unaffected.

The jndiprovider.properties files may specify additional properties, but documentation for the service provider should clearly describe which properties are valid in this file and under what circumstances.

To summarize the search order and precedence for JNDI environment properties, the earliest having highest precedence:

 1. environment parameter used to initialize an initial context,
 2. applet parameters, (only used if that environment param does not exist)
 3. system properties, (only used if that environment and applet parameter 
 do not exist)
 4. application resource files.
 

It should be noted that in the case of applet parameters and system properties only a subset of the properties are read. These are the following 7:

 java.naming.dns.url
 java.naming.factory.control
 java.naming.factory.initial
 java.naming.factory.object
 java.naming.factory.state
 java.naming.factory.url.pkgs
 java.naming.provider.url
 

For a JNDI property found in more than one of those sources, if it is one of the JNDI factory list properties then values are joined into a colon-separated list, otherwise the first instance of a property defines the value to be used.

The above search order and precedence applies when creating contexts for any class implementing the Context interface.

Although a subcontext inherits the environment of its parent context, subsequent changes to either's environment has no direct effect on the other. However, applications should avoid dependency on when JNDI properties are used or verified as this depends on the service provider implementation. As the environment of a context can be examined by any object that has a reference to the context, care should be taken to assess the risk to any security details stored in the environment.

Multithreaded access to a single Context instance is only safe when client code uses appropriate synchronization and locking.

When a NamingEnumeration is returned by a Context method, the operation should not be considered complete, for concurrency purposes, if the NamingEnumeration is still being used or if any referrals are still being followed resulting from that operation.

• "follow" service provider should always follow referrals
• "ignore" service provider should ignore referrals
• "throw" service provider should throw ReferralException if it encounters a referral

Care must be taken with composite names crossing multiple naming systems. A composite name containing a name component which is bound to an object in a different naming system cannot be used to destroy that name subcontext because the subcontext is not of the same type as the context containing the binding. Unbind() can be used to destroy the binding of the specified name in this context to the object in the other naming system. To remove the context object in the other naming system, first obtain a context belonging to the other naming system, then use destroySubcontext() on that context.

Care must be taken with composite names crossing multiple naming systems. A composite name containing a name component which is bound to an object in a different naming system cannot be used to destroy that name subcontext because the subcontext is not of the same type as the context containing the binding. Unbind() can be used to destroy the binding of the specified name in this context to the object in the other naming system. To remove the context object in the other naming system, first obtain a context belonging to the other naming system, then use destroySubcontext() on that context.