ReadMe

Anh Huynh
Takuya Yamashita
University of Hawaii

Welcome to this README file. This file introduces you to the major components of this software package. It includes information on the contents of the package you have downloaded, instructions on how to install the system, basic invocation and usage, user documentation, developer documentation, and contact coordinates for further information.

A. Contents of this package

Directory/File	Contents
.	Top-level directory files include:: README.html (this document) build.xml (the Ant build configuration file) SetEnv.bat (a configuration script for Windows) SetEnv.csh (a configuration script for Unix c-shell) restart.bat (script for undeploying and redeploying the application and restarting tomcat)
./lib	Contains data files used to build and/or run the system: Ant1.4.1/lib: .jar files for running Ant and compiling the system.. JBuilder/: JBuilder project file. manifest: The manifest file providing the main-class value for the .jar file.
./src	Contains the source files.
./build	Contains various products of the build process, including: api/: Contains javadoc API information, created by 'ant javadoc'. size_data/: Contains size data on the system, created by 'ant locc' src_html:/ Contains HTML version of the source code, created by 'ant j2h' dist/ Contains any distributions built during development. These links won't work until their corresponding ant target has been executed.

B. Installation

These instructions assume that you have unzipped the zip file containing this system to create a directory containing the system components. A note to Unix users: due to a bug in java.util.zip, the directory permissions are munged if you unzip in Unix, and you won't be able to cd into interior directories. To fix this, invoke the following from the parent directory of this system: chmod -R a+x <system directory>.

Download and install the Java SDK version 1.3 or above.

The canonical site for obtaining Java SDKs is http://java.sun.com/.

Download and install the Tomcat web server version 4.0.1 or above.
- The canonical site for obtaining Tomcat is http://jakarta.apache.org/tomcat.
Set the JAVA_HOME environment variable to the top-level directory of the Java SDK.

The procedure for setting environment variables is different on Windows, Mac, and Unix; consult your sysadmin or google if you do not know how to set environment variables.
An example value for JAVA_HOME on a windows environment is: c:\jdk1.3.

Set the CATALINA_HOME environment variable to the top-level directory of the Tomcat 4.0.1 installation.
Set the TEST_HOST environment variable to the host where Tomcat will be running.

A typical and common value is: http://localhost:8080/. Please remember to add the final slash.

Bring up a command shell, and cd into this directory (i.e. the directory containing this README.html file.)
Invoke SetEnv to set additional environment variables in this command shell.
- Successful invocation of SetEnv depends upon the platform. On windows, you simply type 'setenv' to invoke the SetEnv.bat file. On Unix (c shell), you type 'source SetEnv.csh' to invoke the c shell version of this batch file.
- Here is the results from an example invocation of this batch file on a windows platform:
```
C:\ics\kin415\ldap>setenv

Build environment settings:
CLASSPATH:     (unset)
TEST_HOST:     http://localhost:8080/
JAVA_HOME:     c:\jdk1.3
.
ANT_HOME:      .\lib\Ant1.4.1
ANT_OPTS:       -Dtest_host=http://localhost:8080/ -Dcatalina_home="c:\jakarta-tomcat-4.0.1"
.
CATALINA_HOME: c:\jakarta-tomcat-4.0.1
CATALINA_OPTS:  -Dtest_host=http://localhost:8080/ -Dcatalina_home="c:\jakarta-tomcat-4.0.1"
```
  Notice that the CLASSPATH environment variable is cleared, that JAVA_HOME and TEST_HOST are whatever you've set them to, that a new environment variable called ANT_HOME has been set to point into this distribution, and that the PATH variable now includes the Ant bin/, Java bin/, and Tomcat/bin directories.

Invoke 'ant' with no arguments to perform the default build of the system.

This command compiles the system, builds the war file, and deploys it on your Tomcat web server.

Here is example output from successful invocation of the 'ant' command:

C:\ics415\ldap>ant
Buildfile: build.xml

init:

prepare:
    [mkdir] Created dir: C:\ics415\ldap\build
    [mkdir] Created dir: C:\ics415\ldap\build\src
    [mkdir] Created dir: C:\ics415\ldap\build\classes
     [copy] Copying 22 files to C:\ics415\ldap\build\src

compile:
    [javac] Compiling 17 source files to C:\ics415\ldap\build\classes

package:
      [jar] Building jar: C:\ics415\ldap\lib\Ant1.4.1\lib\ldap.jar

war:
    [mkdir] Created dir: C:\ics415\ldap\build\webapp
     [copy] Copying 1 file to C:\ics415\ldap\webapp\WEB-INF\lib
     [copy] Copying 1 file to C:\ics415\ldap\webapp\WEB-INF\lib
     [copy] Copying 5 files to C:\ics415\ldap\build\webapp
     [copy] Copying 6 files to C:\ics415\ldap\build\webapp
      [war] Building war: C:\ics415\ldap\lib\ldap.war

deploy:
   [delete] Deleting directory C:\jakarta-tomcat-4.0.1\webapps\ldap
     [copy] Copying 1 file to C:\jakarta-tomcat-4.0.1\webapps

BUILD SUCCESSFUL

Total time: 9 seconds
C:\ics415\ldap>

Bring up your tomcat server by typing 'startup'.

C. Invocation

Using the LDAP system involves building it, deploying it to the Tomcat webserver webapps directory, starting up Tomcat, and then viewing the LDAP page in a browser:

Change directory to the ldap home directory. For e.g., c:\ics415\ldap
Invoke setenv to set your environment variables.
Invoke 'ant' to build the war file and deploy it.
Invoke 'startup' to start up Tomcat.
Visit the ldap's welcome.jsp page. For a default Tomcat installation on the local host, this is located at: http://localhost:8080/ldap/welcome.jsp
Play with the system by login into the system and change password, first name, or last name.

D. User documentation

To Login:
- Enter username in the "User Name" field
- Enter password in the "Password" field
- Click "Login" to authenticate with LDAP and login into the system
- An error will be displayed if the username and password entered are not valid
To change password:
- Enter your password in the "Password" field
- Enter the new value for password in the "Enter Password" field
- Re-enter your new password for verification
- Click "Update" to commit the changes
- An error will be displayed if the specify account does not exist or the password you entered is incorrect
To change first name:
- Enter your password in the "Password" field
- Enter the new value for first name in the "First Name" field
- Click "Update" to commit the changes
- An error will be displayed if the specify account does not exist or the password you entered is incorrect
To change last name:
- Enter your password in the "Password" field
- Enter the new value for last name in the "Last Name" field
- Click "Update" to commit the changes
- An error will be displayed if the specify account does not exist or the password you entered is incorrect

E. Developer documentation

The ldap build system is based on Jakarta Ant. The build.xml file contains targets for compiling, building the JavaDocs, JUnit testing, and so forth. Invoke 'ant -projecthelp' for a complete list of targets. Some of the more helpful ones include:
- compile: compiles the code.
- dist: creates a zip file containing a distribution of the system.
- locc: counts the total size of the system
- javadoc: creates the API design documentation
- test: runs all of the JUnit tests associated with this system.
- checkstyle: checks the source code for comformance to various style conventions
- clean: deletes the files created by the build process.
- j2h: creates an HTML version of the source suitable for code reviews and browsing.
- war: builds the ldap war file.
- deploy (default): Deploys the ldap system onto tomcat. This is the target that is run when ant is invoked with no arguments.
- undeploy: Undeploys the ldap system from the tomcat.
- updateJSP: Updates the changes to JSP pages in the tomcat repository.

F. Contact information

If you would like to know more about this software, or would like to be informed of future releases:

Home page: http://www2.hawaii.edu/~huynha
Developer contact: Anh Huynh (huynha@hawaii.edu), Takuya Yamashita (takuyay@hawaii.edu)
Developer and user mailing lists: not available.