How to use Java Naming & Directory Interface (JNDI) in a J2EE application?

Naming Concepts

i.Naming Service
A fundamental facility in any computing system is the naming service-the means by which the names are associated with objects & objects are found based on their names.
For e.g, 

• when you use an electronic mail system, you must provide recipient's email address
  
• Internet Domain Naming System (DNS) maps machine names to IP addresses. For e.g www.oracle.com => 99.99.99.99
  
• A file system maps a file name to a file reference. For e.g c:\bin\text.txt => File reference

ii. Names
To lookup an object in a naming system,you must supply the name of the object. The syntax is called system's naming convention.
Naming System       Component Separator  Names
Unix File System       "/"                                /usr/Hello
DNS                         "."                               www.oracle.com
LDAP                        "," & "="                     cn=barani,cn=users, dc=company,dc=com

iii.Bindings
The association of a name with an object is called a binding. An LDAP name is bound to an LDAP entry.
iv. Context
A context is a set of "name-to-object" binding. A context always provides a lookup operation that returns the object.
What is a directory service?
Directory Service= Naming Service + Directory objects containing attributes

Java Naming & Directory Interface
It is an API that provides naming & directory functionality to applications written in Java. Some of the key interfaces available are

a) Context
The javax.naming defines a "Context" interface which is the core interface for looking up , binding/unbinding & creating/destroying sub-contexts.

b) InitialContext
In the JNDI, all the naming & directory operations are performed relative to a context. There are no absolute roots. Therefore, JNDI defines an InitialContext which provides a starting point for naming & directory operations.

c) DirContext
It represents a directory context. It behaves as a naming context by extending the getAttributes() to retrieve the attributes associated with the directory entry.

Java Naming and Directory Interface in OC4J
JNDI, in the form of jndi.jar, is available with OC4J. J2EE-compatible applications use JNDI to obtain naming contexts that enable the application to locate and retrieve objects such as data sources, local & remote EJBs, JMS services, and many other J2EE
objects and services.
i. Initial Context
The two most often-used JNDI operations in the J2EE applications are 

• Creating a new InitialContext object
  
• Using the InitialContext, looking up a J2EE or other resource
  

When OC4J starts up, it constructs a JNDI initial context for each application.
ii.Constructing a JNDI context
The environment that OC4J uses to construct a JNDI initial context can be found in several places. These include:

• System property values, as set either by the OC4J server or possibly by the application container
  
• A jndi.properties file contained in the application EAR file
  
• An environment specified explicitly in a Hashtable passed to the JNDI initial context constructor

The JNDI InitialContext has two constructors:

1.  InitialContext()
   
2.  InitialContext(Hashtable env)
   

The second form of the InitialContext constructor is normally used in client applications. The env parameter in the constructor is a Hashtable that contains properties required by JNDI. These properties are:

1. INITIAL_CONTEXT_FACTORY
2. PROVIDER_URL
   
3. SECURITY_PRINCIPAL
   
4. SECURITY_CREDENTIAL
   

INITIAL_CONTEXT_FACTORY
A value for the java.naming.factory.initial property that specifies which initial context factory to use when creating a new initial context object.

PROVIDER_URL
The URL that application client code uses to look up objects on the server.

SECURITY_PRINCIPAL
The user name. Required in application client code to authenticate the client.

SECURITY_CREDENTIAL
The password. Required in application client code to authenticate the client

There are three JNDI initial context factories that are available for use by application code. They are

1. ApplicationClientInitialContextFactory
   
2. ApplicationInitialContextFactory
   
3. RMIInitialContextFactory
   

The following sections describe each of these factories and their uses in OC4J applications

I. ApplicationClientInitialContextFactory
When an application client needs to look up a resource that is available in a J2EE server application, the client uses ApplicationClientInitialContextFactory as to construct the initial context.

Consider an application client that consists of Java code running outside the OC4J server, but that is part of a bundled J2EE application. For example, the client code running on a workstation and might connect to a server object, such as an EJB, to perform some application task. In this case, the environment accessible to JNDI must specify the value of the property java.naming.factory.initial as ApplicationClientInitialContextFactory.

Using the ApplicationClientInitialContextFactory to construct JNDI initial contexts means that the client can look up local objects using the java:comp/env mechanism, and can use ORMI to look up remote objects.

Example
...
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,
"com.evermind.server.ApplicationClientInitialContextFactory");
env.put(Context.PROVIDER_URL,"ormi://<hostname>/employee");
env.put(Context.SECURITY_PRINCIPAL, "admin");
env.put(Context.SECURITY_CREDENTIALS, "welcome");
Context context = new InitialContext(env);
//do the lookups...
...
II. ApplicationInitialContextFactory
Server-side clients need not specify an InitialContextFactory in order to look up resources defined within the client application. By default, serverside clients have InitialContextFactory set to ApplicationInitialContextFactory. 
Example

try {
InitialContext ic = new InitialContext();
ds = (DataSource) ic.lookup("java:comp/env/jdbc/OracleDS1");
...
}
catch (NamingException ne) {
throw new ServletException(ne);
}
...
III. RMIInitialContextFactory
Using either the default server-side ApplicationInitialContextFactory, or specifying ApplicationClientInitialContextFactory, will work for most application purposes.

RMIInitialContextFactory is used when doing a general lookup for external JNDI objects, that may or may not be part of a J2EE application. A generalized JNDI object browser would be an example of this usage.