This article demonstrates how to leverage XML, LDAP, and Java technologies to create a Web-based directory lookup tool. This tool is built with a publicly available implementation of a Java/XML publishing framework called Cocoon (available at http://xml.apache.org/cocoon) and an LDAP server (we tested with the iPlanet Directory Server on Solaris). Using these off-the-shelf modules we can focus on the role of XML as a database-neutral format for data, and how it enables a flexible application architecture that lets you support both wireless and wireline clients. We'll demonstrate this with a WML client (WAP phone simulator on Windows) and an SVG client (Adobe's SVG plug-in for browsers on Windows).

This article assumes the reader has a fairly good knowledge of XML and a working knowledge of XSL stylesheets. We'll first introduce WML (Wireless Markup Language) and SVG (Scalable Vector Graphics), then take a quick tour of LDAP and the Cocoon framework. Finally, we'll tie all the pieces together (the stylesheets, LDAP data source, XML "content" file) to form the application. Since we'll be using the Cocoon framework servlet, you won't need to write any Java code to try this demo.

What Is WML?
WML is an XML standard for wireless devices and part of the Wireless Application Protocol (WAP). It's designed to overcome the lack of support for wireless clients in HTTP and TCP/IP protocols. While HTML browsers have the metaphor of a page, WML browsers have the corresponding notion of "decks," which in turn contain "cards" that are designed to accommodate the limited viewing area and bandwidth available for small wireless devices. The deck is the basic wireless document. A WML application can consist of a few decks. Keep in mind that different devices may display WML decks differently depending on their specific hardware characteristics. The comments in the WML stylesheet explain the features we're using for this example application. For more information on WAP, refer to the following Web site: www.wapforum.org.

What Is SVG?
SVG is a new XML-based language from the W3C that defines two-dimensional graphics. Since it's an XML grammar, SVG is human readable, dynamic, and interactive, with searchable and selectable text. Also, it's a vector format, so graphics are high quality at any resolution and can be zoomed in (or out) without degradation of the image. For more information see the SVG section on the W3C Web site at www.w3c.org/Graphics/SVG.

LDAP
LDAP (Lightweight Directory Access Protocol) is a standard extensible directory access protocol. Several vendors have LDAP implementations (see www.openLDAP.org for a free implementation). You can also download an evaluation version of iPlanet's Directory server from www.iplanet.com/downloads. In addition to being a network protocol, LDAP standards also define (among other things) an Information Model that defines the kind of data you can put into the directory and a Naming Model that defines how you can organize and refer to your directory data. LDAP is optimal for systems in which the data doesn't change often; the predominant operation on the LDAP repository is "read-only" of the data. LDAP also defines a text-based format for describing directory information called LDAP Data Interchange Format or LDIF. We'll use this format to load our directory data. LDAP schema consists of Object class(es) and attributes. Object classes in LDAP contain attributes that can have string, integer, and binary data or pointers to other LDAP objects. Object classes may contain two types of attributes: Allowed (optional) or Required.

Cocoon
Cocoon runs under the Tomcat servlet engine and handles the XML-document processing on the server side. Compared to traditional Web authoring, Cocoon lets you have XML documents instead of HTML, and enables separation of content from presentation.

Cocoon's page processing and caching showcases the feasibility of XML-based publishing for real-world applications. With Cocoon, application users can access XML documents that may also embed queries to data repositories. The query result set from the repository is converted into XML and inserted into the original XML document, which is then transformed into a format the client is capable of handling (WML or SVG in this example).

The Big Picture
Figure 1 shows how all the pieces fit together. We'll discuss the details as we go along. All the "building blocks" you need for this demo application are provided in the "Software to be Downloaded" sidebar above. We recommend you install the components in the same order and test your install at each step. Note the instructions for installing the iPlanet Directory Server: select installation option 2 (typical) and the install script will prompt for the creation of a new directory suffix (o=joeschmoecompany.com). This step is very important for importing our sample LDIF data.

Tomcat servlet engine can be configured to handle XML documents; that is, URLs can refer to XML documents with the .xml extension. If you follow the Cocoon install instructions, then Tomcat is configured to pass on all URL requests for XML documents to the Cocoon servlet. These steps (configuring the Tomcat servlet engine and the Cocoon framework to run under Tomcat) enable us to embed LDAP queries in XML documents using special XML tags that Cocoon supports. The Cocoon framework then fetches the LDAP query results, converts them to an XML document, and applies the appropriate XSL stylesheet. The dotted arrow in Figure 1 shows the relation between the stylesheets and the XML source document. The XML document can have XML Processing Instructions that actually refer to the stylesheet(s) for each output method (WML and SVG in our case).

The Details
Now let's see what goes on inside the LDAP server in Figure 1. We'll use the LDIF format to load the directory data into the LDAP server you've installed. The main benefit of working with the LDIF format is that it's easy to write simple tools to create LDIF files from other existing data sources. Listing 1 shows a Perl script that takes a simple "|" delimited file and creates an LDIF output file. We show the use of a simple text file with one record (entry) per line, with a "|" separating each attribute in the record. Each entry takes the following form: Last name, First name, User ID, Employee number, E-mail address, Department#, Phone number, Location, Building.

Here's an example line of input for the Perl script:

SCHMOE| JOE| jschmoe| 3| joe. schmoe@ joeschmoecompany. com
|14777|( 650) 555 1212 |MenloPark,CA| MenloPark_ Bldg1

The comments in the Perl code explain how the LDIF entries are created. You may want to add more entries like the one above in order to play around with sample data that makes sense to you. The Perl script takes one command line argument - the text file (with the records in the above format) - and creates the LDIF file with the .ldif extension appended to the input file name. LDIF is where we do all the back-end work, so let's look at an example entry. LDIF entries contain mnemonic-named attributes and text values. The first attribute for each entry is the DN (distinguished name) attribute. This attribute should be unique for each entry in the LDAP server. The comma-separated parts that make up the DN are called relative distinguished names (RDNs). This is similar to file system path names. You compose the name of an LDAP entry by appending all the names of the parent entries back to the root. To continue this analogy: the basic LDAP model is also tree-structured just like a file system hierarchy. (This analogy breaks, however, in the manner in which DNs are composed: the least significant component is written first, with the more significant components written subsequently.) We'll make the most basic choice for our LDAP namespace and go with a simple scheme. Here's how the entry looks:

dn: uid= jschmoe, ou= people, o= joeschmoecompany. com
departmentnumber: 14777
cn: Joe Schmoe
uid: jschmoe
sn: Schmoe
telephonenumber: 650 555 1212
mail: joe. schmoe@ joeschmoecompany. com
l: Menlo Park, CA
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson

An example of how Cocoon tags each directory search result is:

<searchresult ID=" uid= jschmoe, ou= people, o= demo">
<telephonenumber> 408 555 1212 </ telephonenumber>
<cn> JOE SCHMOE </ cn>
<uid> jschmo</ uid>
<sn> Schmoe</ sn>
<l> Menlo Park, CA </ l>
<employeenumber> 3 </ employeenumber>
</ searchresult>

Note: There's no DTD here and Cocoon uses the nonvalidating XML parser by default. We've shown only the directory attributes that are of interest to us. So far we've reviewed how the directory records look in XML. The stylesheets in Listings 2 and 3 demonstrate how Cocoon processes and transforms requests for directory lookup. You'll recognize all the XML tags in the stylesheets and relate them to the directory records returned from the search query. Figure 2 shows the Directory Server console after the install. Notice how iPlanet Directory Server creates branching points called organizational units (mnemonic: ou).

Importing LDIF Data
Run the Perl script to create the LDIF output file. The output file should look similar to Listings 4a and b. Figure 3 shows how to use the iPlanet Directory Server's administration tool to load the LDIF file into the Directory Server. Figure 4 shows our directory after the LDIF data file is imported.

At this point we're ready to test the transformation to WML and SVG. However, there's one last configuration change we have to do before we can test-drive the clients.

Configuring Cocoon for SVG
If you've followed the Cocoon installation instructions for Tomcat, the cocoon properties file (cocoon.properties) would be copied under the $TOMCAT_HOME/webapps/ROOT/conf directory. Locate and comment the configuration information for SVG (see Listing 5). This ensures that Cocoon can correctly set up the MIME header for the response as "image/svg-xml" so the SVG plug-in will be activated from the browser for IE or Netscape clients (Windows only, since we're covering the SVG plug-in for Windows). Restart the Tomcat servlet engine so these configuration changes become effective.

Test Drive
Download and save the XML file and the stylesheets (shown in Listings 3, 4, 6, and 7 respectively) under $TOMCAT_HOME/webapps/ROOT/ directory, the default context. Install Phone.com's WAP simulator and Adobe's SVG plug-in. To test drive the WML client, bring up the UP simulator on your Windows machine. Type in the URL http://< tomcathost>:[tomcatport#]/lookup.xml? name=schmoe. Your search result should be similar to Figure 5.

Typing the same URL from IE browser on Windows, your SVG search result should be similar to Figure 6. Try the zoom in/zoom out features with the SVG client. You have now successfully tested this multiclient application!

Conclusion
You've seen how we've used Cocoon's LDAP processor and its XML-processing capabilities to separate content from presentation and support WML and SVG clients. Remember, WML decks should be small (even though they're compiled into a compressed form by WAP gateways) to be reliably delivered onto WAP phones. In real-world WAP phone applications, the compiled deck should be about 500 bytes (approximately 1,500 bytes for the UP.Browser we used for this article). The WAP simulator works over HTTP protocol, whereas in the real world you'll need to run a WAP gateway to handle the protocol conversion between the Web server and the WAP clients.

Even though we've tested the server-side components on Solaris and the clients on Windows, the application should work equally well on other platforms. At the time of this writing, it's the authors' understanding that Microsoft's Active Directory Server's schema doesn't support the inetOrgPerson object class.

We didn't focus on handling multiple search hits in a scalable manner. We suggest you look at iPlanet Directory Server's Virtual List View if you want to implement support for large search result sets. iPlanet Directory Server can also do soundex matches (~= search operator). Since WAP phones typically have more smarts than regular ones, the WAP application environment has a public WTAI (Wireless Telephony Applications Interface) that integrates the telephone and the WAP (micro) browser functions of a WAP device. In the case of our directory lookup application, you can use these functions to call a phone number from the search hit list, add it to the address book, and more. Cellular carriers usually run the WTAI servers.