The JNDI Module

The InitialContextFactory provides a simple way for getting instances of InitialContexts. The InitialContextFactory provides functionality for storing all or some InitialContext environment properties in configuration. For completeness, it also provides methods where all environment properties can be specified programatically.

This section is for those who are not familiar JNDI.

JNDI providers often require some amount of configuration to connect to the JNDI server. Examples of this information include the factory class to use to create the intial context (different than the InitialContextFactory described in this document), a URL locating the sever, and security information. Grouped together, this information is called the environment and are conveyed via key/value pairs in a Map. There are some standard keys that can be found in the javax.naming.Context javadoc and there are others that are specific to the JNDI provider that you are using.

The InitialContextFactory has 2 sets of methods, one for getting javax.naming.InitialContext instances for use with naming services and one for getting javax.naming.directory.InitialDirContext instances for use with directory services. There are 3 methods in each set, one for getting a context using solely configuration to populate the environment properties, one for getting a context where some environment properties can be programatically specified and the rest are supplied via configuration, and one where all environment properties are specified programmatically.

Getting InitialContexts

// Gets a new InitialContext instance with evironment values that come from 
// the service's configuration.
InitialContext getContext() throws NamingException;

// Gets a new InitialContext instance with evironment values that come
// from the service's configuration, but environment values can also
// be passed via the environment parameter to augment or override the
// values stored in configuration.
InitialContext getContext(Map environment) throws NamingException;

// Gets a new InitialContext with environment values given in the
// evironment parameter. The service's configuration is ignored.
InitialContext getContextIgnoreConfig(Map environment) throws NamingException;

Getting InitialDirContexts

// Gets a new InitialDirContext instance with evironment values that come from 
// the service's configuration.
InitialContext getDirContext() throws NamingException;

// Gets a new InitialDirContext instance with evironment values that come
// from the service's configuration, but environment values can also
// be passed via the environment parameter to augment or override the
// values stored in configuration.
InitialContext getDirContext(Map environment) throws NamingException;

// Gets a new InitialDirContext with environment values given in the
// evironment parameter. The service's configuration is ignored.
InitialContext getDirContextIgnoreConfig(Map environment) throws NamingException;

The configuration of this service is a single map of environment properties. The keys of the map are the same keys that would be used when constructing an initial context manually. The standard keys are documented in the javax.naming.Context javadoc.

Example InitialContextFactory Configuration

<Configuration  ConfigurationInterface="org.sape.carbon.services.jndi.InitialContextFactoryConfiguration">
  <FunctionalInterface>org.sape.carbon.services.jndi.InitialContextFactory</FunctionalInterface>
  <FunctionalImplementationClass>org.sape.carbon.services.jndi.DefaultInitialContextFactoryImpl</FunctionalImplementationClass>

  <EnvironmentMap>
    <Environment Key="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</Environment>
    <Environment Key="java.naming.provider.url">ldap://localhost:1396</Environment>
    <Environment Key="java.naming.security.principal">cn=admin,dc=example,dc=com</Environment>
    <Environment Key="java.naming.security.credentials">password</Environment>
  </EnvironmentMap>
</Configuration>