DAP (Lightweight Directory Access Protocol) is the defacto standard in many enterprises for organizing and managing directory services (employee directory, network URLs, etc.). Common implementations include Netscape’s Directory Server, IBM’s Tivoli Directory Server, and OpenLDAP.

While not a tutorial on LDAP itself, this article walks through the process of obtaining the necessary LDAP client software (Netscape Directory SDK), building it from source (avoiding the need to purchase a license and binary distribution from Sun), and briefly testing the interface with Netscape Directory Server. (For good resources on LDAP, see the Related Resources section of this article).

To follow the instructions, you need Netscape Directory Server 4.x and J2SE 1.2.x or higher installed. Since Netscape Directory Server is no longer distributed (Sun has incorporated the original codebase into its iPlanet Directory Server as a part of Sun ONE), finding current documentation on this process can be rather difficult.

Getting the Source
Building the Netscape Directory Server SDK requires one source bundle (the Netscape Directory SDK for Java), while another source bundle is optional (Jakarta-ORO Java library). If all you need to do is bind, lookup, modify, and delete LDAP entries, then the Netscape Directory SDK for Java is sufficient. If, however, you want to apply filters to your LDAP searches and incorporate regular expression matching, you need the Jakarta-ORO Java library.

• Netscape Directory SDK for Java (required)
  1. Open www.mozilla.org/directory in your favorite browser. (I prefer Mozilla Firebird.)
  2. Click the “LDAP Java SDK” link.
  3. Download the tar (Linux and Unix platforms) or zip (Windows).
  4. Alternately, you can check the source out of CVS directly (instructions further down the page).
• Jakarta-ORO Java library (optional)
  1. Open jakarta.apache.org/oro in your favorite browser.
  2. Click the “Download” link on the left.
  3. Scroll down a LONG way (or you can search for ‘ORO’, and skip the first result).
  4. Download the tar (Linux and Unix platforms) or zip (Windows).
  5. Alternately, you can check the source out of CVS directly (instructions available via link on the left at the top of the page).

Building the SDK from Source
Building the SDK from source would seem to be a straightforward process, but my personal experiences have proved otherwise. While it can be a very easy process that you practically sleepwalk through, it also can be quite involved, requiring several detailed steps. The aim of this section is to streamline the process for you as much as possible.

You can build the source in two ways: using make files or using Ant. The source code ships with both. For those of you who are familiar and comfortable with make files, you are welcome to use them to build the source. I personally find this approach to be very frustrating. If you select this approach, follow the build instructions for your platform as detailed here.I recommend the Ant approach, which is both Java-centric and cross-platform. Follow these steps to build with Ant:

1. Extract the files.
2. Navigate to mozilladirectoryjava-sdk.
3. Type ant.
4. Study the list of targets and run the target(s) that you need.

For a basic build, I recommend the following targets:

ant dist-docsant dist-jdk

This will build the JavaDocs for the SDK (mozilladirectoryjava-sdkdistdoc), as well as a JAR file containing the basic LDAP access classes (mozilladirectoryjava-sdkdistpackages).

Building the LDAP Filters (Reg Exp with Jakarta-ORO)
The filter classes enhance the basic SDK by supporting regular expression filtering of LDAP entries in a lookup/search procedure. The filter classes written for the SDK rely upon an external regular expression engine developed by Daniel Savarese and distributed by ORO, Inc. Savarese founded ORO and donated the source code to the Apache Jakarta project in June 2000. At the time that the SDK classes were written, ORO still owned the software, thus the package namespaces begin with “com.oroinc”. Once Apache received the software, it changed the packaging to match its naming conventions (org.apache.oro).

In order to successfully compile the filter classes, you must change all references to the old ORO packaging to reference the new names. Fortunately, the API has remained untouched in every other way (class names, method signatures, etc.), so the necessary changes are relatively minor.

The compilation steps are as follows:

1. Navigate to mozilladirectoryjava-sdkldapfilter
   etscapeldaputil.
2. Change the import statements in: LDAPFilterDescriptor.java, LDAPIntFilterList.java, LDAPIntFilterSet.java from com.oroinc.text.regex.* to org.apache.oro.text.regex.*.
3. Save and close the source files.
4. Navigate to mozilladirectoryjava-sdk.
5. Open the build.properties file.
6. Uncomment the last line (remove the # sign).
7. Change the path so that it points to the Jakarta-ORO jar file (jakarta-oro-x.x.x.jar).
8. Save and close the file.
9. Run ant build to build the entire SDK, or ant dist-filter to build just the filter JAR.

Now that you have built the SDK (either in part or in whole), you are ready to try it out.

Testing the Interface
The first step is to include the JAR file(s) in your system classpath. This could be as simple as including ldapjdk.jar, ldapjdk.jar and jakarta-oro-2.0.8.jar, or all of the Netscape Directory SDK jars in your classpath. The simple test in this article requires you to place only the ldapjdk.jar file in your classpath.

With your classpath set up, you are prepared to write a test program. The following are the five essential steps for performing an LDAP operation on a server:

1. Create a new LDAPConnection object.
   Use a variable of type LDAPv2 or LDAPv3 to ensure that the API you are using is appropriate for your server’s LDAP version support.
2. Use the connect() method to connect to the LDAP server.
   LDAPv2 declares two connect() methods: one that accepts a host and port, another that also accepts a name and password for authentication. LDAPv3 adds a connect() method that allows you to specify the LDAP version number.
3. Use the authenticate() method to authenticate to the server.
   If you didn’t authenticate in the connect() method, then you will need to invoke authenticate() separately. For LDAPv2, supply a name and password. LDAPv3 adds an authenticate() method that accepts an LDAP version number.
4. Perform the LDAP operation.
   You have a variety of LDAP operations (add an entry, compare entries, delete an entry, modify an entry, read an entry, rename an entry, search entries, etc.) and corresponding methods.
5. Use the disconnect() method to disconnect from the server when done.
   As with any external resource, closing the server connection when you are through is important. You typically can best handle this in a finally{} block.

To see a complete example, download the accompanying source code for this article.

The JNDI Service Provider
A common best practice for J2EE application development is using the Java Naming and Directory Interface (JNDI) to serve as an abstraction layer on top of naming and directory services. This allows you to write your business logic and use JNDI to serve as a proxy for naming and directory operations, which a JNDI LDAP service provider then passes on to the LDAP server.

The Netscape Directory Server SDK ships with a JNDI LDAP service provider. You can generate the JNDI LDAP Service Provider JAR (ldapsp.jar) from source using the ant target dist-jndi. For more information about the API and how to use it, read Chapter 15 of the “Netscape Directory SDK for Java Programmer’s Guide”.

Great LDAP Servers Never Die…
The Netscape Directory Server is a great LDAP server that, although no longer in production, is reliable enough for many large enterprises to use. If you find yourself needing to access this server programmatically via Java, you will likely need to build the SDK from source. This article has shown you the steps involved in building the SDK in a cross-platform way, as well as provided some tips on using the SDK’s API to access the server.

I encourage you to download and study the source code and make use of the many resources I identified in the Related Resources section. Enjoy!