Software Setup

«« Previous
Next »»

Java Platform Software

JNDI is included in the Java SE Platform.

To run the applets, you can use any Java-compatible Web browser, such as Firefox, or Internet Explorer v5 or later. To ensure that your applets take full advantage of the latest features of the Java platform software, you can use the Java Plug-in with your Web browser.

Service Provider Software

The JNDI API is a generic API for accessing any naming or directory service. Actual access to a naming or directory service is enabled by plugging in a service provider under the JNDI.

A service provider is software that maps the JNDI API to actual calls to the naming or directory server. Typically, the roles of the service provider and that of the naming/directory server differ. In the terminology of client/server software, the JNDI and the service provider are the client (called the JNDI client) and the naming/directory server is the server.

Clients and servers may interact in many ways. In one common way, they use a network protocol so that the client and server can exist autonomously in a networked environment. The server typically supports many different clients, not only JNDI clients, provided that the clients conform to the specified protocol. The JNDI does not dictate any particular style of interaction between JNDI clients and servers. For example, at one extreme the client and server could be the same entity.

You need to obtain the classes for the service providers that you will be using. For example, if you plan to use the JNDI to access an LDAP directory server, then you would need software for an LDAP service provider.

The JDK comes with service providers for:

◈ Light Weight Directory Protocol (LDAP)
◈ CORBA Common Object Services naming (COS naming)
◈ RMI registry
◈ Domain Name Service (DNS)

If you are interested in other providers please check the JNDI page for download information.

This tutorial uses only the LDAP Service provider. When using the LDAP service provider, you need either to set up your own server or to have access to an existing server, as explained next.

Naming and Directory Server Software

Once you have obtained the service provider software, you then need to set up or have access to a corresponding naming/directory server. Setting up a naming/directory server is typically the job of a network system administrator. Different vendors have different installation procedures for their naming/directory servers. Some require special machine privileges before the server can be installed. You should consult the naming/directory server software's installation instructions.

For the directory examples in this tutorial, you need access to an LDAP server. If you would like to take a quick tour of what LDAP is check out here. You can use any LDAP-compliant server of your choice. The Oracle Directory Server, which runs on many platforms, including Windows, is available for evaluation at: Oracle Directory Server.

You can also download free LDAP servers below:

◈ OpenDS
◈ OpenLDAP
◈ 389 Directory Server
◈ Apache Directory Server

A publicly accessible server is available at: ldap://ldap.openldap.org Naming Context: dc=OpenLDAP,dc=org

LDAP Setup


Below are the steps involved in building a Java Application that accesses an LDAP Directory Server.

1. Install the Java Platform Software.
2. Get the Directory Server software as discussed earlier.
3. Configure the Directory Server with the desired schema. For using the examples in this tutorial a special schema needs to be configured on the server.
4. Populate the directory server with the desired content. For using the examples in this tutorial a special content needs to be populated on the server.
5. Write a JNDI application to access the Directory, compile and run it against the Directory Server to get your desired results. The JNDI examples are covered in the next lesson.

The first two steps are covered in the previous section. The rest of this lesson discusses steps three and part of step four. The step five that involves writing a JNDI application is covered in the next lesson that shows how to write JNDI applications to perform various operations on the directory.

Once you've set up the directory, or have directed your program to communicate with an existing directory, what sort of information can you expect to find there?

The directory can be viewed as consisting of name-to-object bindings. That is, each object in the directory has a corresponding name. You can retrieve an object in the directory by looking up its name.

Also stored in the directory are attributes. An object in the directory, in addition to having a name, also has an optional set of attributes. You can ask the directory for an object's attributes, as well as ask it to search for an object that has certain attributes.

Step 3: Directory Schema

A schema specifies the types of objects that a directory may contain. This tutorial populates the directory with entries, some of which require special schema definitions. To accommodate these entries, you must first either turn off schema-checking in the server or add the schema files that accompany this tutorial to the server. Both of these tasks are typically performed by the directory server's administrator.

This tutorial comes with two schema files that must be installed:

◈ Schema for Java objects
◈ Schema for CORBA objects

The format of these files is a formal description that possibly cannot be directly copied and pasted into server configuration files. Specifically, the attribute syntaxes are described in terms of RFC 2252.

Different directory servers have different ways of configuring their schema. This tutorial includes some tools for installing the Java and CORBA schemas on directory servers that permit their schemas to be modified via the LDAP. Following is a list of tasks the tools can perform.

1. Create Java Schema
2. Create CORBA Schema

Follow the instructions in the accompanying README file to run these programs.

Note: Windows Active Directory. Active Directory manages its schema by using an internal format. To update the schema, you can use either the Active Directory Management Console snap-in, ADSIEdit, or the CreateJavaSchema utility, following the instructions for Active Directory.

Step 4: Providing Directory Content for This Tutorial

In the examples of this trail, the results shown reflect how the LDAP directory has been set up using the configuration file ( tutorial.ldif ) that accompanies this tutorial. If you are using an existing server, or a server with a different setup, then you might see different results. Before you can load the configuration file ( tutorial.ldif ) into the directory server, you must follow the instructions for updating the server's schema or you can use ldapadd or ldapmodify command if available on your UNIX system.

For example, using ldapmodify you could do (by plugging in appropriate values for the hostname, administrator DN (-D option), and the password):

ldapmodify -a -c -v -h hostname -p 389\
        -D "cn=Administrator, cn=users, dc=xxx, dc=xxx"\
        -w passwd -f tutorial.ldif

Installation Note: Access Control. Different directory servers handle access control differently. Some examples in this tutorial perform updates to the directory. Also, the part of the namespace where you have installed the tutorial might have read access restrictions. Therefore, you need to take server-specific actions to make the directory readable and/or updatable in order for those examples to work. For the Oracle Directory Server add the aci entry suggested in the sunds.aci.ldif file to the dn: o=JNDITutorial entry to make the entire directory readable and updatable. Alternatively, you may change the examples so that they authenticate to the directory. Details of how to do this are described in the Security lesson.

Installation Note: Namespace Setup. The entries in the tutorial.ldif file use the distinguished name (DN) "o=JNDITutorial" for the root naming context. If you have not configured your directory server to have "o=JNDITutorial" as a root naming context, then your attempt to import tutorial.ldif will fail. The easiest way to get around this problem is to add the DN of an existing root naming context to each "dn:" line in the tutorial.ldif file. For example, if your server already has the root naming context "dc=imc,dc=org", then you should change the line

dn: o=JNDITutorial

to

dn: o=JNDITutorial, dc=imc, dc=org

Make this change for each line that begins with "dn:" in the file. Then, in all of the examples in this tutorial, wherever it uses "o=JNDITutorial", use "o=JNDITutorial,dc=imc,dc=org" instead.

Installation Note: File Format. Depending on the operating system platform that you are using, you might need to edit tutorial.ldif so that it contains the correct newline characters for that platform. For example, if you find that tutorial.ldif contains Windows-style newline characters (CRLF) and you are importing this file into a directory server that is running on a UNIX platform, then you need to edit the file and replace CRLF with LF. A symptom of this problem is that the directory server rejects all of the entries in tutorial.ldif.

Installation Note: Windows Active Directory.

1. The root naming context is not going to be "o=jnditutorial". It will be of the form "dc=x,dc=y,dc=z". You need to follow the previous Namespace Setup note.

2. Add the object classes and related attributes for the "inetOrgPerson" and "groupOfUniqueNames" object classes to the Active Directory schema by using the Active Directory Management Console snap-in, ADSIEdit. "groupOfUniqueNames" is defined in RFC 2256 , "inetOrgPerson" in RFC 2798.

3. Some of hierarchical relationships used by the tutorial are not allowed by default in Active Directory. To enable these relationships, add them by using the Active Directory Management Console snap-in, ADSIEdit.

objectclass: organizationalUnit
possible superiors: domainDNS
                    inetOrgPerson
                    organizaton
                    organizationalPerson
                    organizationalUnit
                    person
                    top

objectclass: groupOfUniqueNames
possible superiors: top

objectclass: inetOrgPerson
possible superiors: container
                    organizationalPerson
                    person
                    top

4. Delete one of the two "sn" attributes from the Mark Twain entry in tutorial.ldif. Active Directory defines "sn" to be a single-valued attribute, contrary to RFC 2256.

5. Use the ldifde command-line utility to load the modified tutorial.ldif file.
# ldifde -i -v -k -f tutorial.ldif

6. Most of the examples assume that the directory has been set up to permit unauthenticated read and update access. Your Active Directory setup might not allow you to do that. See the Access Control installation note.

7. Reading an entry sometimes produces more attributes than are shown in the tutorial because Active Directory often returns some internal attributes.

8. Creation of entries might require the specification of additional Active Directory-specific attributes or the use of other object classes.

Java Application Setup


To use the JNDI in your program, you need to set up its compilation and execution environments.

Importing the JNDI Classes

Following are the JNDI packages:

javax.naming
javax.naming.directory
javax.naming.event
javax.naming.ldap
javax.naming.spi

The examples in this trail use classes and interfaces from the first two packages. You need to import these two packages into your program or import individual classes and interfaces that you use. The following two lines import all of the classes and interfaces from the two packages javax.naming and javax.naming.directory.

import javax.naming.*;
import javax.naming.directory.*;

Compilation Environment

To compile a program that uses the JNDI, you need access to the JNDI classes. The Java SE 6 already include the JNDI classes, so if you are using it you need not take further actions.

Execution Environment

To run a program that uses the JNDI, you need access to the JNDI classes and classes for any service providers that the program uses. The Java Runtime Environment (JRE) 6 already includes the JNDI classes and service providers for LDAP, COS naming, the RMI registry and the DNS .

If you are using some other service providers, then you need to download and install their archive files in the JAVA_HOME/jre/lib/ext directory, where JAVA_HOME is the directory that contains the JRE. The JNDI page lists some service providers. You may download these providers or use providers from other vendors.

«« Previous
Next »»