Previous     Contents     Index     Next     
iPlanet Directory Server Resource Kit 5.1 Tools Reference



Chapter 29   jdgw Phone Book


The jdgw (JSP™ Directory Gateway) Phone Book is a sample application that demonstrates how a web-based client may access iPlanet Directory Server through JavaServer Pages™ (JSP) technology. The application presents a simple interface in any browser for searching and editing the contents of an enterprise phone book.

The gateway consists of three components that make an LDAP directory accessible through HTML pages. First, the Tomcat web server of the Apache Jakarta project provides a JSP framework and a standard tag library. The tags are XML-like structures that contain the logic to generate the HTML page contents.

The second component is an LDAP tag library which use the iPlanet LDAP SDK for Java to query a directory server and process the response. The last component is a set of JSP files containing servlets and using the two tag libraries to perform the user's request and format the response to be displayed as HTML.

The iPlanet DSRK includes all three components, but you will need to install the Tomcat server and download the Java 2 Platform, version 1.3.1 if necessary. You can then use the sample phone book application to access any directory containing entries representing people.

Finally, you can customize the JSP files to tailor the HTML output to your needs. You may also use the LDAP tag library to develop new JSP files that will implement your own gateway application.

This chapter contains the following sections:



Software Installation

The installation procedure for the jdgw Phone Book application includes the following steps:

  1. Download and install the Java 2 Platform, Standard Edition, version 1.3.1 if you do not already have it.

  2. Install the Tomcat web server provided in the iPlanet DSRK installation, or download and install the latest version, and test the installation.

  3. Optionally, install the standard tag library (JSPTL) provided in the product installation, or download and install the latest version (now known as JSTL). Configure the web server to view the JSPTL documentation and examples.

  4. Configure the jdgw application to access your LDAP directory server, and then configure the web server to use the jdgw files.

The following sections describe the installation procedure for each of these software packages.


Java 2 Platform, v1.3.1

The JSP standard tag library 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 freely available from Sun Microsystems at the following URL:

http://java.sun.com/j2se/1.3/

Run the setup program for the software you download and follow the installation instructions. The instructions in this chapter will use JDKdir to refer to the directory where you install J2SE 1.3.1.

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


Tomcat Web Server, v4.0 or Later

The iPlanet DSRK product includes the files for installing the Tomcat web server, version 4.01, which is the latest available at release time. Use one of the following files in the installDir /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 at the location where you wish to install the product.

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

Or 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

These installation instructions will use TomcatDir to refer to the base directory where you installed the Tomcat web server. Start the web server with one of the following sets of commands, according to your platform:

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

    export CATALINA_HOME=TomcatDir
     export JAVA_HOME=JDKdir
    TomcatDir     /bin/startup.sh

  • On a Windows platform, in a DOS command window:

    set CATALINA_HOME=TomcatDir
     set JAVA_HOME=JDKdir
    TomcatDir     \bin\startup.bat

Catalina is the name of the Tomcat 4.0 release. 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 iPlanet DSRK installation also includes the files for installing the JSP Tag Library (JSPTL), Early Access Release 1.2, which is the latest available at release time. Installing the JSPTL is optional because the Phone Book application already contains a copy of the tag library's jar file. Install the full JSPTL if you wish to learn about the tag library, view its documentation, and run its examples.

Use one of the following files in the installDir /jdgw/apache-downloads/jsptl1.2/ directory, according to your platform:

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

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

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

http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html


Note As of publication time, the JSP Standard Tag Library is now called JSTL and is available as a Beta 1 release. This release has a new 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 example, but the Phone Book application must use the old JSPTL jar files that were installed with the jdgw application.


To view the JSPTL documentation and examples, you must edit the configuration file named TomcatDir /conf/server.xml to include the following definitions below the root context definition. These definitions assume that the JSPTL is installed in a directory named JSPTLdir :

<!-- JSPTL Doc Context -->
<Context path="/jsptl-doc" docBase="JSPTLdir/jsptl-doc.war"
         debug="0" reloadable="true">
    <Logger className="org.apache.catlina.logger.FileLogger"
            prefix="jsptl_doc_log." suffix=".txt"
            timestamp="true"/>
</Context>

<!-- JSPTL Examples Context -->
<Context path="/jsptl-examples" debug="0" reloadable="true"
         docBase="JSPTLdir/jsptl-examples.war">
    <Logger className="org.apache.catlina.logger.FileLogger"
            prefix="jsptl_examples_log." suffix=".txt"
            timestamp="true"/>
</Context>

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

  • On a Solaris or UNIX platform:

    TomcatDir /bin/shutdown.sh
    TomcatDir /bin/startup.sh

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

    TomcatDir \bin\shutdown.bat
    TomcatDir \bin\startup.bat

Now the JSPTL documentation and examples should be available at the following URLs:

http://localhost:8080/jsptl-doc
http://localhost:8080/jsptl-examples



File Configuration

Once you have installed the required software, you will need to configure the phone book application and add its context definition to the server.

The phone book application uses the configuration files located in the installDir /jdgw/phonebook-app/properties directory. You need to edit the file named lookmeup.properties to specify the directory server that will be queried by the jdgw application. For example, the file might contain:

hostname=test.siroe.com
port=389
base=ou=people,dc=siroe,dc=com
country=US
language=en

As shown above, this file 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.

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 theses files unless you wish to change the output of the sample application. See "Customization" for more information.

Finally, you need to add the following context definition for the jdgw application to the Tomcat server configuration in the TomcatDir /conf/server.xml file:

<!-- JDGW LookMeUp phone book application -->
<Context path="/jdgw" docBase="InstallDir /jdgw/phonebook-app"
         debug="0" reloadable="true">
    <Logger className="org.apache.catlina.logger.FileLogger"
            prefix="jdgw_log." suffix=".txt"
            timestamp="true"/>
</Context>

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

  • On a Solaris or UNIX platform:

    TomcatDir /bin/shutdown.sh
    TomcatDir /bin/startup.sh

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

    TomcatDir \bin\shutdown.bat
    TomcatDir \bin\startup.bat



Sample HTML Output

When the full installation and file configuration are completed successfully, you will be able to access the sample jdgw application called LookMeUp at the following URL:

http://localhost:8080/jdgw/jsp/lookmeup

This application is a simple employee phone book. It will search for people in your directory and display the results in easy-to-read tables. The following figure shows the introductory search page at the URL given above.

Figure 29-1    Index Page of the LookMeUp Application



Customization


Coming soon.

Previous     Contents     Index     Next     
Copyright 2002 Sun Microsystems, Inc.. All rights reserved.

Last Updated April 15, 2002