Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun ONE Directory Server Resource Kit 5.2 Tools Reference 

Chapter 32
JSP Directory Gateway Phonebook

The JavaServer Pages™ Directory Gateway is a sample application that demonstrates how a web-based client may access Sun™ ONE Directory Server through JSP technology. The application presents a simple browser interface for searching and editing the contents of an enterprise phonebook. This chapter provides instructions on how to use the application. It contains the following sections:


A gateway is a client that lives on a HyperText Transfer Protocol (HTTP) server and offers access to Lightweight Directory Access Protocol (LDAP) directory data using a web browser. A gateway can be used to perform directory lookup, or to authenticate to the directory and complete database administration tasks. The JavaServer Pages (JSP) Directory Gateway (jdgw) is a phonebook application that can be used to access any directory containing entries representing people. The phonebook application itself is called LookMeUp. It is comprised of three components that allow an LDAP directory to be accessible through HTML. All three components can be found in the DSRK_base/jdgw directory. They are:

Apache Software

The DSRK_base/jdgw/apache-downloads directory itself contains three products from the Jakarta project of The Apache Software Foundation (ASF).


The Jakarta Project creates and maintains open source Java solutions.

Included with the DSRK are the following Jakarta components.

LDAP Tag Libraries

The DSRK_base/jdgw/ldap-taglib directory contains a LDAP tag library which uses the Sun ONE LDAP SDK for Java to query a directory server and process the response. You may use the LDAP tag library to develop new JSP to implement your own version of the gateway application. Again, Chapter 33, "Tag Library Reference" details the tag libraries.

LookMeUp Application Files

The DSRK_base/jdgw/phonebook-app directory contains the set of JSP and related files needed to set up the phonebook application called LookMeUp. You can customize the JSP files to tailor the HTML output.

Software Installation

The installation procedure for the JSP Directory Gateway is:

  1. Download and install the Java 2 Platform, Standard Edition, version 1.3.1 if you do not already have it. More information can be found in Java 2 Platform, v1.3.1.
  2. Install the Tomcat web server provided with the DSRK, or download and install the latest version. More information can be found in Tomcat Web Server, v4.0 or Later.
  3. Install version 1.2 of the JavaServer Pages Tag Library (JSPTL) provided with the DSRK. More information can be found in JSP Standard Tag Library.
  4. Configure LookMeUp to access your LDAP directory server and the web server to use the jdgw files. More information can be found in Post-Installation Configuration.

Java 2 Platform, v1.3.1

The JSPTL included with LookMeUp requires the Java 2 Platform, Standard Edition (J2SE™), version 1.3.1, also know as the JDK™ 1.3.1. If you do not already have this software, it is available from Sun Microsystems at:

Download the software and run the setup program, following the installation instructions provided with the download.


The instructions in this chapter will use JDK_base to refer to the directory where you install J2SE 1.3.1.

On UNIX platforms, you will need to add JDK_base/bin to your environment’s PATH variable. On Windows platforms, the installer will automatically update your registry with the JDK path.

Tomcat Web Server, v4.0 or Later

The DSRK includes files for installing the Tomcat web server, version 4.01. Use one of the files in the DSRK_base/jdgw/apache-downloads/tomcat4.01/ directory, according to your platform:

Alternately, you may download a later version from the Jakarta project web site and install it in the same manner:


The instructions in this chapter will use Tomcat_base to refer to the directory where you install the Tomcat web server. Catalina is the name of the Tomcat 4.0 servlet container.

Starting the Server

Once installed, start the web server with one of the following sets of commands, according to your platform:

The file RUNNING.txt (found in the directory in which the application is uncompressed) includes more information.

Testing the Server and Accessing Tomcat Documentation

Test your Tomcat web server installation by accessing the following URL in any browser:

http://localhost:8080/ or http://hostname:8080/

You should see the default index.html file of the server. From this page, you can access the links to run examples of JSP pages and servlets. There is also a link to the Tomcat documentation which is installed locally:


JSP Standard Tag Library

The DSRK installation includes the files for installing the JSP Tag Library (JSPTL), Early Access Release 1.2, which was the latest available at release time. Installing the JSPTL is optional because LookMeUp already contains a copy of the tag library’s jar file but, if you wish to learn about the tag library by viewing its documentation and running its examples, the full JSPTL needs to be installed. (Chapter 33, "Tag Library Reference" details the libraries themselves.) Use one of the following files in the DSRK_base/jdgw/apache-downloads/jsptl1.2/ directory to install:

Viewing the JSPTL Documentation

To view the JSPTL documentation and examples, you must edit the configuration file named Tomcat_base/conf/server.xml to include the definitions below the root context definition reproduced in Code Example 32-1. These definitions assume that the JSPTL is installed in a directory named JSPTL_base.

Code Example 32-1  server.xml Configuration File 

<!-- JSPTL Doc Context -->

<Context path="/jsptl-doc" docBase="JSPTL_base/jsptl-doc.war"

         debug="0" reloadable="true">

    <Logger className="org.apache.catalina.logger.FileLogger"

            prefix="jsptl_doc_log." suffix=".txt"



<!-- JSPTL Examples Context -->

<Context path="/jsptl-examples" debug="0" reloadable="true"


    <Logger className="org.apache.catalina.logger.FileLogger"

            prefix="jsptl_examples_log." suffix=".txt"



After modifying the server configuration file, restart the Tomcat server with the following commands:

The JSPTL documentation and examples should now be available at:


Post-Installation Configuration

Once the required software is installed, you will need to configure the LookMeUp application and the Tomcat server.

LookMeUp Configuration

LookMeUp uses the configuration files located in the DSRK_base/jdgw/phonebook-app/WEB-INF/classes directory. You need to edit the file named to specify the directory server that will be queried by LookMeUp.


The file and the file contain text that is used by the JSP files to generate HTML output. You do not need to modify these files unless you wish to change the output of the sample application.

Code Example 32-2 is an example of (which also contains parameters for specifying the base or suffix of all phone book searches and the country and language locale of input and output text).

Code Example 32-2 File





Tomcat Server Configuration

You also need to add the context definition for LookMeUp to the Tomcat server configuration file server.xml located in the Tomcat_base/conf/ directory. server.xml is duplicated in Code Example 32-3.

Code Example 32-3  server.xml File 

<!-- JDGW LookMeUp phone book application -->

<Context path="/jdgw" docBase="InstallDir/jdgw/phonebook-app"

         debug="0" reloadable="true">

    <Logger className="org.apache.catalina.logger.FileLogger"

            prefix="jdgw_log." suffix=".txt"



After modifying server.xml, restart the Tomcat server using either of the following:

Accessing LookMeUp

When the full installation and file configuration are successfully completed, you will be able to access LookMeUp at:


LookMeUp is a simple employee phonebook. It will search for people in your directory and display the results in easy-to-read tables. The basic elements of the application are templates that contain HTML elements with LDAPTL, JSPTL, and UTILTL elements in places where dynamic content will be inserted in the generated page sent to the client browser. Figure 32-1 shows the introductory search page for the application.

Figure 32-1  Index Page of the LookMeUp Application

Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.