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:

Overview

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).


Note	The Jakarta Project creates and maintains open source Java solutions.

Apache Ant 1.4.1 is a Java-based build tool. It is in the DSRK_base/jdgw/apache-downloads/ant1.4.1 directory.

The JavaServer Pages Tag Libraries (JSPTL) standard can be found in the DSRK_base/jdgw/apache-downloads/jsptl1.2 directory. The tags are XML-like structures that contain the logic to generate the HTML page contents. Chapter 33, "Tag Library Reference" details the tag libraries.

The Tomcat web server provides a framework from which LookMeUp’s JSP can be run.

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

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.

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.

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.

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.


Note	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:

jakarta-tomcat-4.0.1.tar.gz or jakarta-tomcat-4.0.1.zip on Solaris and UNIX platforms. These files contain all Tomcat web server files, which you should uncompress in the directory where you wish to install the product using:

gzip -d < jakarta-tomcat-4.0.1.tar.gz | tar xvfm - for the .gz file.

unzip jakarta-tomcat-4.0.1.zip for the .zip file.

jakarta-tomcat-4.0.1.exe is a self-extracting installer program for Windows platforms. Run this file and choose a location for the installation.

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

Starting the Server

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


Note	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.

On a Solaris^™ or UNIX platform, using the Korn shell for example:

export CATALINA_HOME=Tomcat_base
export JAVA_HOME=JDK_base
Tomcat_base/bin/startup.sh

On a Windows platform, in a DOS command window:

set CATALINA_HOME=Tomcat_base
set JAVA_HOME=JDK_base
Tomcat_base\bin\startup.bat

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:

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:

jakarta-taglibs-jsptl-ea1.2.tar.gz on Solaris and UNIX platforms. Uncompress this file in the directory of your choice.

jakarta-taglibs-jsptl-ea1.2.zip on Windows platforms. Uncompress this file in the directory of your choice.



Note	Later versions of the included JSPTL are now abbreviated and known as JavaServer Pages Standard Tag Library (JSTL). The new versions have a different structure and its files are not compatible with the jdgw application. You may still download the new release to view its documentation and run the examples, but the application must use the older JSPTL jar files.

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"
timestamp="true"/>
</Context>
<!-- JSPTL Examples Context -->
<Context path="/jsptl-examples" debug="0" reloadable="true"
docBase="JSPTL_base/jsptl-examples.war">
<Logger className="org.apache.catalina.logger.FileLogger"
prefix="jsptl_examples_log." suffix=".txt"
timestamp="true"/>
</Context>

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

On a Solaris or UNIX platform:

Tomcat_base/bin/shutdown.sh
Tomcat_base/bin/startup.sh

On a Windows platform, in the same DOS command window:

Tomcat_base\bin\shutdown.bat
Tomcat_base\bin\startup.bat

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 lookmeup.properties to specify the directory server that will be queried by LookMeUp.



Caution	The screen.properties file and the ldaperrors.properties 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 lookmeup.properties (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 lookmeup.properties File


hostname=directory.example.com
port=389
base=ou=people,dc=example,dc=com
country=US
language=en

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"
timestamp="true"/>
</Context>

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

On a Solaris or UNIX platform:

Tomcat_base/bin/shutdown.sh
Tomcat_base/bin/startup.sh

On a Windows platform, in the same DOS command window:

Tomcat_base\bin\shutdown.bat
Tomcat_base\bin\startup.bat

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.

Previous Contents Index Next
Sun ONE Directory Server Resource Kit 5.2 Tools Reference