Previous | Next | Trail Map | Getting Started | JNDI Overview

Naming Package

The javax.naming(in the API reference documentation) package contains classes and interfaces for accessing naming services.


The javax.naming package defines a Context(in the API reference documentation) interface, which is the core interface for looking up, binding/unbinding, renaming objects and creating and destroying subcontexts.

The most commonly used operation is lookup()(in the API reference documentation). You supply lookup() the name of the object you want to look up, and it returns the object bound to that name. For example, the following code fragment looks up a printer and sends a document to the printer object to be printed.

Printer printer = (Printer)ctx.lookup("treekiller");


Every naming method in the Context interface has two overloads: one that accepts a Name(in the API reference documentation) argument and one that accepts a java.lang.String name. Name is an interface that represents a generic name--an ordered sequence of zero or more components. For the methods in the Context interface, a Name argument that is an instance of CompositeName(in the API reference documentation) represents a composite name , so you can name an object using a name that spans multiple namespaces. A Name argument of any other type represents a compound name. (Names are covered in the Beyond the Basics (in the Beyond the Basics trail) trail.) The overloads that accept Name are useful for applications that need to manipulate names, that is, composing them, comparing components, and so on.

A java.lang.String name argument represents a composite name. The overloads that accept java.lang.String names are likely to be more useful for simple applications, such as those that simply read in a name and look up the corresponding object.


listBindings()(in the API reference documentation) returns an enumeration of name-to-object bindings. Each binding is represented by an instance of the Binding(in the API reference documentation) class. A binding is a tuple containing the name of the bound object, the name of the object's class, and the object itself.

list()(in the API reference documentation) is similar to listBindings(), except that it returns an enumeration of NameClassPair(in the API reference documentation). NameClassPair contains an object's name and the name of the object's class. list() is useful for applications such as browsers that want to discover information about the objects bound within a context but that don't need all of the actual objects. Although listBindings() provides all of the same information, it is potentially a much more expensive operation.


Objects are stored in naming and directory services in different ways. A service that supports storing Java objects might support storing an object in its serialized form. However, some naming and directory services do not support the storing of Java objects. Furthermore, for some objects in the directory, Java programs are but one group of applications that access them. In this case, a serialized Java object might not be the most appropriate representation. A reference might be a very compact representation of an object, whereas its serialized form might contain a lot more state (see the Naming Concepts (in the Getting Started trail) lesson).

The JNDI defines the Reference(in the API reference documentation) class to represent a reference. A reference contains information on how to construct a copy of the object. The JNDI will attempt to turn references looked up from the directory into the Java objects that they represent so that JNDI clients have the illusion that what is stored in the directory are Java objects.

The Initial Context

In the JNDI, all naming and directory operations are performed relative to a context. There are no absolute roots. Therefore the JNDI defines an initial context, InitialContext(in the API reference documentation), which provides a starting point for naming and directory operations. Once you have an initial context, you can use it to look up other contexts and objects.


The JNDI defines a class hierarchy for exceptions that can be thrown in the course of performing naming and directory operations. The root of this class hierarchy is NamingException(in the API reference documentation). Programs interested in dealing with a particular exception can catch the corresponding subclass of the exception. Otherwise, they should catch NamingException.

Previous | Next | Trail Map | Getting Started | JNDI Overview