Section 9.2. A Simple Example

9.2. A Simple Example

Before going any further, let's take a look at a simple JNDI example. To access an object in a naming system, we need to create an initial context for the naming system, to give us an entry point into it. Once we have an initial context, we can look up an object by name.

Example 9-1 demonstrates the basic JNDI tasks of getting an initial context to a naming system and looking up an object in that naming system. With slight modification, this code can be used to look up objects with any JNDI provider. So, for example, you could use this Lookup class to look up Enterprise JavaBeans or remote objects in an RMI registry and handle them however you like. All you have to change is the properties that control the naming system being accessed.

Example 9-1. Looking up an object in a naming system

 import java.util.Properties; import javax.naming.*;   public class Lookup {   public static void main(String[] args) {     String name = "";     if (args.length > 0)       name = args[0];       try {       // Create a Properties object and set default properties       Properties props = new Properties(  );       props.put(Context.INITIAL_CONTEXT_FACTORY,                 "com.sun.jndi.fscontext.RefFSContextFactory");       props.put(Context.PROVIDER_URL, "file:///");         // Optional command-line args to specify alternate factory and URL       if (args.length > 1) {         props.put(Context.INITIAL_CONTEXT_FACTORY, args[1]);       }       if (args.length > 2) {         props.put(Context.PROVIDER_URL, args[2]);       }           // Create the initial context from the properties we just created       Context initialContext = new InitialContext(props);         // Look up the named object       Object obj = initialContext.lookup(name);       if (name.equals(""))         System.out.println("Looked up the initial context");       else         System.out.println(name + " is bound to: " + obj);     }     catch (NamingException ne) {       System.out.println("Encountered a naming exception");       ne.printStackTrace(  );     }   } }

The first thing the Lookup application does is create a java.util.Properties object and use it to store some String values. The keys used for these values are constants defined in the javax.naming.Context class. Each constant corresponds to an underlying standard JNDI property name that is meant to communicate specific information about the JNDI service the application is using. Context.INITIAL_CONTEXT_FACTORY specifies the factory class that creates an initial context for the service we want to use. The class com.sun.jndi.fscontext.RefFSContextFactory is a factory class from the filesystem service provider from Sun. It isn't provided by default in the Sun JDK downloads, but it can be downloaded from http://java.sun.com/products/jndi. Context.PROVIDER_URL tells the factory class the protocol, server name, and path to use in creating an initial context. We specify the URL file:/// to indicate the root of the local filesystem. This works on any Unix or Windows filesystem.

Once we have created the Properties object and set the default values for the context factory and the provider URL, we check the command-line arguments for specific values that the user may have provided. Finally, we pass the Properties to the javax.naming.InitialContext constructor, which returns the initial context object that is our entry point into this particular naming system. Next, we call the lookup( ) method on initialContext, specifying the name we want to look up. This call returns an object from the naming system, which, in this case, is a file or directory.

You can run Lookup from the command line and specify an optional name to look up. For example, on a typical Windows machine:

 % java Lookup boot.ini boot.ini is bound to: C:\boot.ini

If the name is actually a directory, the output looks a bit different:

 % java Lookup System System is bound to: com.sun.jndi.fscontext.RefFSContext@803adec0

Note that if we wanted to make Lookup more general, we might change it so that it reads its property values from a properties file. Luckily, JNDI takes care of this for you; it automatically loads any of its standard properties from a jndi.properties file if it finds the file in your CLASSPATH. Changing the naming system is a simple matter of editing this properties file to specify an appropriate factory object and URL. You can always override the properties loaded from jndi.properties in your code, as we've done in the Lookup example. In the next section, we'll discuss the properties that can be set to control how JNDI operates.

JNDI throws naming exceptions when naming operations can't be completed. The root naming exception, javax.naming.NamingException, is a catchall for any JNDI exception. The javax.naming package defines numerous subclasses of NamingException. A common naming exception, NameNotFoundException, is thrown when a name can't be found, because it either doesn't exist or is spelled incorrectly. JNDI throws a NoPermissionException when a program doesn't have sufficient rights or permissions and throws an OperationNotSupportedException when an application uses a JNDI method on an object that doesn't support that specific naming operation.