Sun ONE Directory Server Resource Kit 5.2 Tools Reference |
Chapter 32
JSP Directory Gateway PhonebookThe 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:
OverviewA 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).
Included with the DSRK are the following Jakarta components.
- 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 InstallationThe installation procedure for the JSP Directory Gateway is:
- 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:
- 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:
http://jakarta.apache.org/site/binindex.html
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.
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:
http://localhost:8080/tomcat-docs/index.html
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.
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.
After modifying the server configuration file, restart the Tomcat server with the following commands:
The JSPTL documentation and examples should now be available at:
http://localhost:8080/jsptl-doc
http://localhost:8080/jsptl-examples
Post-Installation ConfigurationOnce 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:
Accessing LookMeUpWhen the full installation and file configuration are successfully completed, you will be able to access LookMeUp at:
http://localhost:8080/jdgw/jsp/lookmeup
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