The Java Naming and Directory Interface

Java continues the unification and standardization process to enable developers to use enterprise technologies with the JNDI API. The JNDI API provides a standard and consistent way for Java applications to access naming and directory services implemented by different vendors or service providers.

Similar to the way JDBC API drivers are used to access different databases, the JNDI API can be used to access naming and directory services provided by different vendors.

JNDI comprises the JNDI API and the JNDI SPI. The JNDI API (application programming interface) is the interface that developers deal with. The JNDI SPI (service provider interface) consists of interfaces that vendors of naming and directory services implement to make their naming and directory services compliant and accessible using the JNDI API. The WebLogic Server implements the JNDI SPI, which enables applications to access and use WebLogic's naming and directory services using the JNDI API. This lesson will focus on the JNDI API only.

Figure 9.6 shows how JNDI achieves the unification of disparate naming and directory service providers. The JNDI architecture consists of four layers:

• Vendor-specific naming and directory services At the lowest level, there are different naming and directory services from different service providers, such as LDAP, DNS, NDS, NIS, RMI, CORBA, and so on. To enable the accessing of these services using JNDI, each of the service providers implements the JNDI SPI. This is similar to the JDBC drivers provided by vendors of different databases. So you will find the service provider of, say, LDAP offering a JNDI "driver" by implementing the JNDI SPI. The JNDI SPI is a consistent and common interface that hides the internal implementation of the respective services of different service providers.

• JNDI SPI The JNDI SPI is the lowest layer that directly interacts with the naming service. The JNDI SPI is a set of interfaces that must be implemented by the vendors of naming or directory services to make their services compliant with the JNDI architecture. Because the JNDI SPI layer is a vendor-specific implementation, the intermediate NamingManager and DirectoryManager classes perform the interaction between the JNDI SPI layer and the JNDI API layer.

• NamingManager and DirectoryManager The NamingManager and DirectoryManager classes are responsible for creating the InitialContext object when a client application uses the JNDI API. The DirectoryManager class subclasses the NamingManager class and is responsible for supporting the creation of the DirContext object.

• JNDI API The final layer, used by server components as well as client applications and components, is the JNDI API layer. The JNDI API layer offers a common and standard mechanism for accessing and using naming and directory services.

Figure 9.6. JNDI architecture.

The next section will be covering the important classes in the JNDI API.

JNDI API

The JNDI API is composed primarily of the following packages:

• javax.naming

• javax.naming.directory

• javax.naming.event

• javax.naming.ldap

• javax.naming.spi

Today's lesson will be focusing on the naming and directory packages because a client using the JNDI API uses the classes in these packages. Now look at the important classes in these two packages in detail.

javax.naming Package

The interfaces and classes used for accessing naming services are organized in the javax.naming package. Interfaces such as Context and Name and classes implementing these different interfaces (IntialContext, CompoundName, and CompositeName) form part of the javax.naming package. Take a look at the different interfaces and classes in this package.

The Context Interface

The Context interface in the javax.naming package is the naming context composed of the name and object bindings. The Context interface contains the bind(), rebind(), rename(), lookup(), list(), createSubcontext(), unbind(), and other methods that are used by client applications and server-side components to access and register themselves with the naming service. Apart from these methods, the Context interface contains constants such as INITIAL_CONTEXT_FACTORY, PROVIDER_URL, SECURITY_CREDENTIALS, and so on that are used to set and retrieve the environment properties for different contexts. The InitialContext class implements the Context interface. Take a look at the important methods in the Context interface:

• bind() The bind() method is used by a server component to register itself with the naming service. The bind() method takes the name with which the server object should be bound and the server object as parameters. The bind() method is overloaded. One bind() method takes the name to be used for binding the object as a string value. When using composite names to make your application support generic names, you should use the overloaded bind() method that wraps the name inside a Name object. The method throws a NameAlreadyBoundException if an object with the same name already exists in the naming service.

• rebind() The rebind() method is a variation of the bind() method. Unlike the bind() method, which attempts to create an entry in the naming service for the name used for binding, the rebind() method overwrites any existing entry with the new server object. Like the bind() method, the rebind() method is overloaded. One version of the rebind() method takes a string name and the server object as parameters. The other version wraps the name to be bound inside a Name object and takes the Name object and the server object as parameters.

• rename() The rename() method is used by the server object to bind a new name to the server object in the naming service. The rename() method is also overloaded and takes the old name and new name as either string parameters or wrapped in Name objects.

• lookup() The lookup() method is used by a JNDI client application to locate server objects. The lookup() method, similar to the bind() method, is overloaded and takes the name with which the server object is bound. The name parameter can be either a string or a Name object. The lookup() method returns the reference of the bound object if successful or null if an object reference is not obtained.

• list() The list() method is used to display the contents of the naming service. The list() method is overloaded and takes the name of the naming context of the naming service as a parameter either in string or Name object format. The name of the naming context can be obtained using the getNameInNamespace() method. The list() method returns a NamingEnumeration object, which is essentially an enumerated list of objects in the naming service. To traverse the contents of the NamingEnumeration object, you can use the hasMore() and next() methods of the NamingEnumeration interface.

• createSubcontext() To create a nested hierarchy of objects in the naming service, you can use the createSubcontext() method. The method takes as a parameter the name of the new context that you need to create under the current context. The name of the context can be passed as either a string or as a Name object (using the getNameInNamespace() method). A successful call to the method results in the creation of a subcontext under the current context and returns the new Context object. You can bind objects to this subcontext, thus creating a nested hierarchy of objects.

• unbind() The unbind() method is used to remove the entry of the object bound in the naming service. The unbind() method is overloaded and takes the name in either a string or Name object format.

• close() To free up the resources used by the current context, you should use the close() method.

The InitialContext Class

The InitialContext class implements all the methods in the Context interface. The IntialContext class is always used when any JNDI operations need to be initiated. Because the InitialContext class implements the Name interface, environment properties to define the state for the InitialContext such as the context provider, security credentials, and so on should be set in an instance of the InitialContext. Hence, a JNDI-compatible service provider will provide the InitialContext class.

The Name Interface

The Name interface of the javax.naming package provides methods to manipulate the names defined for objects in the naming service. The important methods in the Name interface include add(), remove(), size(), startsWith(), and endsWith(). The CompoundName and CompositeName classes implement the Name interface. Service providers of naming services need to provide the CompoundName and CompositeName classes.

The CompoundName Class

The CompoundName class implements the methods in the Name interface. The manipulation methods in the CompoundName are primarily used for working with compound names, that is, names defined in a hierarchical format. The names defined in a compound name format have well-defined syntax and structure rules. Service providers for naming services that support compound names provide an implementation of the CompoundName class. A compound name is a name in a single naming system (for example, LDAP) and is made up of a set of components separated by the separator character of that naming system. The ordering of compound names is from right to left.

Here is an example of a compound name:

 cn=Teach Yourself WebLogic Server 7.0 in 21 Days, ou=SAMS Publishing  

where the two parts of the compound name are

 ou=SAMS Publishing  cn=Teach Yourself WebLogic Server 7.0 in 21 Days 

The CompositeName Class

The CompositeName class implements the methods in the Name interface. The CompositeName class should be used when the names defined for objects in the naming service follow a composite name format, that is, a set of names in different namespaces. Each of these names in a namespace can be a compound name (that is, a hierarchical name) that can be further broken down. Service providers for different naming services that support compound names provide an implementation of the CompoundName class.

Here is an example of a composite name:

 cn=Teach Yourself WebLogic Server 7.0 in 21 Days,          ou=SAMS Publishing/examples/jndisrc/JNDISampleApp.java 

This example shows a composite name in string format representing the contents of two different namespaces: LDAP and a file system. The first part of the composite name is the LDAP compound name, and the remaining parts are the compound names in the file system namespace separated by the / namespace separator. A lookup() method call using this composite name returns the File object for the JNDISampleApp.java file.

javax.naming.directory Package

The javax.naming.directory package contains interfaces and classes used for accessing directory services. Interfaces such as DirContext, Attribute, and Attributes and classes implementing these different interfaces (IntialDirContext, BasicAttribute, and BasicAttributes) form part of the javax.naming.directory package. Take a look at the different interfaces and classes in this package.

The DirContext Interface

The DirContext interface in the javax.naming.directory package extends the javax.naming.Context interface. The DirContext provides additional methods for manipulating attributes associated with objects and names in the directory service. The important methods in the DirContext interface are bind(), createSubContext(), rebind(), and search(). Methods such as bind() and createSubContext() are overloaded to deal with manipulation of attributes along with names and to deal with the same methods (with different signatures) inherited from the Context interface. The InitialDirContext class implements the DirContext interface. Service providers of different directory services need to provide the InitialDirContext class that implements the DirContext interface.

Now you'll look at some methods that demonstrate the use of attributes with names in the directory service.

• bind() The bind() method is similar to the bind() method in the InitialContext interface, with the exception that it takes the Attributes object as an additional parameter. This maintains the association of the name and attributes with the server object in the directory service. The bind() method is overloaded and accepts the name for binding as either a string or Name object.

• rebind() Like the rebind() method in the InitialContext, the rebind() for the DirContext overwrites an existing entry in the directory service. The rebind() method is overloaded and takes as parameters the name to be used for binding (as a string or Name object), the server object, and the attributes to be stored.

• createSubcontext() The createSubcontext() method is used to create a nested context under the current context with the name of the new context and the attributes for the new context as parameters. A successful execution of the createSubcontext() method returns the newly created DirContext object. The createSubcontext() method is overloaded to accept the name of the new subcontext in either string or Name object format.

• search() The search() method is the most frequently used method in the DirContext interface and is overloaded to enable developers to use different combinations for searching. At the simplest level, the search() method takes as param eters the name used to bind the object and the attributes to match. The search() method always returns the NamingEnumeration object that contains an enumeration of all the server objects registered with the context in the directory service that matched the name and search attributes used to perform the search. To perform more fine-grained and complex searches, you can use the SearchControls class. The SearchControls class allows developers to define parameters that limit the scope of the search.

The InitialDirContext Class

The InitialDirContext class implements the methods in the DirContext interface. Like the InitialContext class that provides the functionality for the methods in the Context interface, the InitialDirContext class provides the functionality for the methods in the DirContext class. Moreover, because the InitialDirContext class also extends the InitialContext class, it automatically inherits the functionality that implements the methods in the Context interface.

The Attribute Interface

The Attribute interface in the javax.naming.directory package defines the ways to access and manipulate an attribute of an object in a namespace. An attribute can contain zero or more values that may or may not be ordered. The important methods in the Attribute interface are add(), remove(), get(), set(), and so on. The BasicAttribute class in the javax.naming.directory package implements the Attribute interface.

The BasicAttribute Class

The BasicAttribute class in the javax.naming.directory package implements the methods in the Attribute interface. Server objects that need to set an attribute along with their name in the directory interface or client applications that need to search objects in a directory service based on an attribute use the BasicAttribute class.

The Attributes Interface

The Attributes interface contains methods to manipulate a collection of Attribute objects. The important methods in this interface are related to retrieving and setting attributes for an object.

The BasicAttributes Class

The BasicAttributes class in the javax.naming.directory package provides the underlying functionality for the methods in the Attributes interface.

Named Resources in WebLogic Server

WebLogic Server supports different types of named resources that can be looked up and used by client applications or components using the JNDI API. Examples of resources that can be registered in the naming service of WebLogic Server are as follows:

• Database connections The implementation class of the DataSource interface can be bound in the naming service and this JDBC connection can be retrieved by different applications or components as needed.

• Message queues and message topics JNDI is the ideal way to store these references.

• EJB components EJB components such as session beans, entity beans, and message beans can be registered in a naming service to make them available to other applications or components. Specifically, the home interface for session beans and entity beans, which is the creation factory for EJBs, is registered in WebLogic Server's naming service.

Because WebLogic Server provides its own implementation of the JNDI SPI, it provides its own implementation of the InitialContext environment and context factory. Context creation using WebLogic Server's extension to the JNDI API can be done in three ways:

• Using a hash table The simplest way to create a context that uses WebLogic Server's implementation of JNDI is to set the Context.INITIAL_CONTEXT_FACTORY property to weblogic.jndi.WLInitialContextFactory in a hash table. Also, the Context.PROVIDER_URL property should be set to the URL where the WebLogic Server is running. The default value for this is t3://localhost:7001. This hash table is then passed to the constructor of the InitialContext class when it creates a new InitialContext object.

• Using the WebLogic Environment class The Environment class is a WebLogic Server specific class that simplifies the creation and setting of values for the InitialContext. To use the Environment class, create a new Environment object. Use the methods provided by the Environment class such as setInitialContextFactory(), setProviderUrl(), setSecurityPrincipal(), setSecurityCredentials(), and so on to set the relevant context factory, provider URL, and security details. After the Environment object is populated with these values, invoke the getInitialContext() method of the Environment class, which returns the constructed javax.naming.Context object.

• On the WebLogic Server side Java classes or EJBs deployed in the WebLogic Server also need to use the JNDI API to look up objects in the naming service. But because these execute within the JVM of WebLogic Server, these server-side objects do not need to set the Context.PROVIDER_URL property using either of the two previous methods. On the server side, a construction of a new InitialContext object automatically populates the Context object with WebLogic Server specific values.