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
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.factory.control C see LdapContext
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
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
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
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
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
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.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
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
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.