Java Naming and Directory Interface Overview

1. Introduction

The Java Naming and Directory Interface (JNDI) provides consistent use of naming and/or directory services as a Java API. This interface can be used for binding objects, looking up or querying objects, as well as detecting changes on the same objects.

While JNDI usage includes a diverse list of supported naming and directory services, in this tutorial we’ll focus on JDBC while exploring JNDI’s API.

2. JNDI Description

Any work with JNDI requires an understanding of the underlying service as well as an accessible implementation. For example, a database connection service calls for specific properties and exception handling.

However, JNDI’s abstraction decouples the connection configuration from the application.

Let’s explore Name and Context, which contain the core functionality of JNDI.

2.1. Name Interface

Name objectName = new CompositeName("java:comp/env/jdbc");

The Name interface provides the ability to manage the component names and syntax for JNDI names. The first token of the string represents the global context, after that each string added represents the next sub-context:

Enumeration<String> elements = objectName.getAll();
while(elements.hasMoreElements()) {
  System.out.println(elements.nextElement());
}

Our output looks like:

java:comp
env
jdbc

As we can see, / is the delimiter for Name sub-contexts. Now, let’s add a sub-context:

objectName.add("example");

Then we test our addition:

assertEquals("example", objectName.get(objectName.size() - 1));

2.2. Context Interface

Context contains the properties for the naming and directory service. Here, let’s use some helper code from Spring for convenience to build a Context:

SimpleNamingContextBuilder builder = new SimpleNamingContextBuilder(); 
builder.activate();

Spring’s SimpleNamingContextBuilder creates a JNDI provider and then activates the builder with the NamingManager:

JndiTemplate jndiTemplate = new JndiTemplate();
ctx = (InitialContext) jndiTemplate.getContext();

Finally, JndiTemplate helps us access the InitialContext.

3. JNDI Object Binding and Lookup

Now that we’ve seen how to use Name and Context, let’s use JNDI to store a JDBC DataSource:

ds = new DriverManagerDataSource("jdbc:h2:mem:mydb");

3.1. Binding JNDI Objects

As we have a context, let’s bind the object to it:

ctx.bind("java:comp/env/jdbc/datasource", ds);

In general, services should store an object reference, serialized data, or attributes in a directory context. It all depends on the needs of the application.

Note that using JNDI this way is less common. Typically, JNDI interfaces with data that is managed outside the application runtime.

However, if the application can already create or find its DataSource, it might be easier to wire that using Spring. In contrast, if something outside of our application bound objects in JNDI, then the application could consume them.

3.2. Looking Up JNDI Objects

Let’s look up our DataSource:

DataSource ds = (DataSource) ctx.lookup("java:comp/env/jdbc/datasource");

And then let’s test to ensure that DataSource is as expected:

assertNotNull(ds.getConnection());

4. Common JNDI Exceptions

Working with JNDI may sometimes result in runtime exceptions. Here are some common ones.

4.1. NameNotFoundException

ctx.lookup("badJndiName");

Since this name is not bound in this context, we see this stack trace:

javax.naming.NameNotFoundException: Name [badJndiName] not bound; 0 bindings: []
  at org.springframework.mock.jndi.SimpleNamingContext.lookup(SimpleNamingContext.java:140)
  at java.naming/javax.naming.InitialContext.lookup(InitialContext.java:409)

We should note that the stack trace contains all objects bound, which is useful for tracking down why the exception occurred.

4.2. NoInitialContextException

Any interaction with the InitialContext can throw NoInitialContextException:

assertThrows(NoInitialContextException.class, () -> {
  JndiTemplate jndiTemplate = new JndiTemplate();
  InitialContext ctx = (InitialContext) jndiTemplate.getContext();
  ctx.lookup("java:comp/env/jdbc/datasource");
}).printStackTrace();

We should note that this use of JNDI is valid, as we used it earlier. However, this time there is no JNDI context provider, and an exception will be thrown:

javax.naming.NoInitialContextException: Need to specify class name in environment or system property, 
  or in an application resource file: java.naming.factory.initial
    at java.naming/javax.naming.spi.NamingManager.getInitialContext(NamingManager.java:685)

5. Role of JNDI in Modern Application Architecture

While JNDI plays less of a role in lightweight, containerized Java applications such as Spring Boot, there are other uses. Three Java technologies that still use JNDI are JDBC, EJB, and JMS. All have a wide array of uses across Java enterprise applications.

For example, a separate DevOps team may manage environment variables such as username and password for a sensitive database connection in all environments. A JNDI resource can be created in the web application container, with JNDI used as a layer of consistent abstraction that works in all environments.

This setup allows developers to create and control a local definition for development purposes while connecting to sensitive resources in a production environment through the same JNDI name.

6. Conclusion

In this tutorial, we saw connecting, binding, and looking up an object using the Java Naming and Directory Interface. We also looked at the common exceptions thrown by JNDI.

Finally, we looked at how JNDI fits into modern application architecture.

As always, the code is available over on GitHub.