Java Naming and Directory Interface

JNDI is a generic interface that provides a common set of functions for accessing naming and directory services. Used together with other J2EE technologies, JNDI can provide a centralized storage mechanism for components in a distributed computing environment.

A naming service in computer terms allows for objects (maybe printers, computers, contacts, or Enterprise JavaBeans) to be associated with a unique name. Using the naming service, applications can then gain access to these resources using their unique name . A directory service is an extension of a naming service that allows for attributes to be associated with the stored objects. There are many different types of naming and directory type services, such as Lightweight Directory Access Protocol (LDAP) (a directory service), DNS (a naming service) and even the file system of your computer. When you use JNDI you can access all these directory services with a standard API that abstracts the underlying implementation of the directory away from your application. For more information on the use of JNDI in general, check out the documentation at http://java.sun.com/products/jndi/ .

Although the directory access capabilities of JNDI are an important part of J2SE, its naming capabilities are a cornerstone of the J2EE environment. All J2EE application servers are required to provide an internal naming service, accessible via JNDI, in which you can store resources for your application. In many cases these resources can be configured externally from your application, allowing for changes to be made to application components without the need to modify the Java code. The implementation of this service is left to the choice of the application server vendor, and for the most part is unimportant to your application. The collection of resource-to-name bindings within the application server is called a context.

The most common resources stored in the application server context are Java Database Connectivity (JDBC) DataSources, Enterprise JavaBeans (EJB) references, Java Message Service (JMS) destinations, and JavaMail sessions. In this chapter you'll see how to set the JNDI location of a DataSource object. You'll find JNDI examples for the other resource types in the relevant chapter, as follows :

• For more information about setting the JNDI location of a JMS connection factory or destination, see Chapter 6.

• For more information about setting the JNDI location of a JavaMail session and about configuring arbitrary environment settings, see Chapter 8.

• For more information about setting the JNDI location of an EJB, see Chapter 11.

In the case of all these resources, Oracle 10g AS allows for external configuration.

Within the JNDI context you can also manually store additional resources for your application. For instance you may have a set of error messages that you want to be available throughout your application. If this is the case you can place them in the JNDI context. However, from a practical point of view, using JNDI resources for what are essentially lightweight resources isn't a good idea. You could just as easily create a simple external Java properties file to store the error messages and load this when your application starts. In practice, JNDI is more suited to storing objects that represent some kind of resource, not just configuration values.

Understanding JNDI Locations

There are three types of JNDI locations, each of which has its own visibility. Global locations can use any namespace (as long as it doesn't begin with java:/ ) and are accessible to any component or client that's allowed to access JNDI. Local locations begin with java:/comp/ and are only accessible to components within the container. Finally, a separate local java:/comp/env/ namespace is configured for each individual component and prepopulated based on its deployment descriptor.

Most resources, such as DataSources, JMS destinations, and JavaMail sessions are bound to global locations such as jdbc/OracleProductDataSource and jms/MQSeriesOrderQueue . Often, these are then mapped to local component references like java:/comp/env/jdbc/ProductDB and java:/comp/env/jms/OrderQueue , which you can look up within your EJB or Servlet code. You can also specify environment entries in your deployment descriptors. These will be made available to your components in the java:/comp/env/ namespace.

Note 

You'll see an example of the global and component-local namespaces in Chapter 8.

The containerwide java:/comp/ namespace is most often used when obtaining a user transaction from java:/comp/UserTransaction . In most cases, however, your applications will deal with the global namespace (for configuration) and the local namespace.

Getting a JNDI Context

To access JNDI, you must first create a javax.naming.InitialContext . This is easy within the container, where all JNDI properties are already configured and you can simply use the default constructor, like this:

 Context ctx = new InitialContext(); 

Client applications, on the other hand, need to first configure the following JNDI properties. These can either be passed as a map to a special InitialContext constructor, or included in a jndi.properties file in the root of the classpath, as shown here:

 java.naming.factory.initial=com.evermind.server.rmi.RMIInitialContextFactory java.naming.provider.url=ormi://localhost/yourApplicationName java.naming.security.principal=admin java.naming.security.credentials=yourAdminPassword 

Customize the URL, principal , and credentials as appropriate for your application. Using the configuration file is the preferable solution since you can avoid hard-coding the attributes into your application.