Webappbuilders.com - Web Application Architecture: Principles, Protocols, and Practices

Instructions for Downloading and Installing the Sample Application

These instructions are geared for installation in a Windows environment. Instructions for UNIX, Linux, or Macintosh systems can be found here.

Download the distribution package for this application. Unzip it into a directory of your choosing.
For purposes of this document, we will assume that you are on a Windows platform and have already downloaded this package and extracted its contents under the C:\myprojects directory. If not, the link for downloading is found below.
[ download the VRLS application distribution package ]
Install the Java Development Kit (JDK) on your system. This is needed both to compile the application and to support the Web application server's servlet and JSP engines.
We recommend JDK version 1.5 or version 1.6 for this application. Both versions are available on Sun's Web site.
[ download JDK 1.5 ] [ download JDK 1.6 ]
Install and configure Apache's Ant tool which is used to build the application.
We recommend using Ant 1.4.1 or better. Also, on systems running Windows, it is recommended that Ant should be installed into a directory with no spaces in its name. (e.g., C:\ant, not C:\program files\ant)
[ download Ant ]
Install and configure your Web application server software. You must use an application server (or "Web container") that includes or supports the usage of a servlet engine (Java Servlet API 2.4 or better) and Java Server Pages (JSP 2.0 or better). It should also support JNDI lookup of configured JDBC DataSources.
If you do not already have a J2EE Web container installed, we recommend Apache Tomcat. It is open source, freely available, and supports all the functionality required by the application. Either version 5.5 or version 6 is recommended.

Remember that Tomcat defaults to using port 8080, so either include the port number in your localhost URLs (e.g., http://localhost:8080) or change Tomcat's configuration to use port 80 for HTTP requests. (Read the Tomcat documentation for instructions on how to do this.)
[ download Tomcat 5.5 ] [ download Tomcat 6 ]
Install and configure your database management system (DBMS). The data model for this application is persisted in a relational database, thus a working database is required. You will also need a JDBC driver appropriate for the DBMS that you choose.
If you do not already have a DBMS installed, we recommend MySQL. Like Apache Tomcat, it is open source, freely available, and supports the functionality required by the application. In fact, the application's data access services were written under the assumption that a simple DBMS like MySQL (which does not support triggers or stored procedures or automated referential integrity) would be used. Version 5.0 is recommended. The JDBC driver for MySQL is included in the download for the DBMS itself, but it is also accessible separately if desired.
[ download MySQL 5.0 ] [ download MySQL JDBC driver ]
Execute the SQL queries that create and populate the database tables used by the application. This process varies depending on which DBMS you are using, so consult the documentation associated with your DBMS software for appropriate instructions. Assuming here that you installed MySQL into the directory named C:\mysql\, enter the following commands to execute these scripts.
```
C:\> cd \mysql\bin
C:\mysql\bin> mysql -u root -p
Enter password: ********
Welcome to the MySQL monitor.  Commands end with ; or \g.

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> use test
Database changed
mysql> source \myprojects\vrlsapp\sql\dbschema.sql
	...
mysql> source \myprojects\vrlsapp\sql\populate.sql
	...
mysql> source \myprojects\vrlsapp\sql\mysqlgrant.sql
	...
```
The dbschema.sql and populate.sql query files in the above files may be imported into SQL processing tools associated with other DBMSs to create and populate the application tables if necessary. The mysqlgrant.sql query file performs SQL grant statements needed if you are using a newly installed MySQL installation, as shown below:
```
grant all on test.* to waabook identified by 'waabook' ;
grant all on test.* to waabook@localhost identified by 'waabook' ;
```
Define the following environment variables. (Methods for doing this vary between Windows, Linux, and Macintosh systems.)

ANT_HOME - the directory in which Ant was installed

e.g., c:\ant

JAVA_HOME - the directory in which the JDK was installed

e.g., c:\jdk

TOMCAT_HOME - the directory in which Tomcat was installed (if you are using Tomcat)

e.g., c:\program files\tomcat
If you are using Tomcat, copy the JAR file containing your DBMS's JDBC driver files into the common/lib directory under TOMCAT_HOME.
```
C:\> cd directory-containing-driver-file
C:\...\> copy mysql-connector-java-5.0.5-bin.jar %TOMCAT_HOME%\common\lib
	
```
If you are using a DBMS other than MySQL, read the documentation for your DBMS to determine where you can find the appropriate drivers.

If you are using a Web container other than Tomcat, follow the instructions regarding where JDBC drivers used for JNDI-defined DataSources belong.
Define a DataSource for the application to use within your application server environment. This process varies depending on which Web container software you are using, so we will concentrate here on Tomcat. Consult the documentation associated with your application server software for appropriate instructions.
In older versions of Tomcat, the most direct way to define the DataSource was to edit the server.xml file found in the %TOMCAT_HOME%\conf directory, adding a DataSource definition to the Tomcat configuration manually.
```
<Context path="/vrls">
    <Resource name="jdbc/vrls"
              type="javax.sql.DataSource"
              password="waabook"
              driverClassName="com.mysql.jdbc.Driver"
              maxIdle="2"
              maxWait="5000"
              validationQuery="select * from vrls_xref_listing_type"
              username="waabook"
              url="jdbc:mysql://localhost:3306/test?autoReconnect=true&amp;jdbcCompliantTruncation=false"
              maxActive="4" />
</Context>
```
Tomcat 5.5 and 6.x let you place a context.xml file containing the above text in a WAR file's META-INF directory. This lets you deploy applications with their own customized resource definitions without having to modify the server's base configuration files. We include a context.xml in the application distribution and place it in the appropriate place in the WAR file as part of the build process. If you are using a different application server, a different DBMS, or different connection credentials, you will need to modify this file before the application is built and deployed.
Build the application using Ant. This is accomplished using a command line interface (shell/terminal window on UNIX/Linux, or DOS prompt in Windows), entering the directory into which you extracted the contents of the application's distribution package, and running Ant.
```
C:\> cd myprojects\vrlsapp
C:\myprojects\vrlsapp> %ANT_HOME%\bin\ant
```
This will cause Ant to look for the build.xml file found in that directory, and use the directives in that file to invoke the Java compiler (%JAVA_HOME%\bin\javac) in order to build the application binaries.

Once the code has successfully compiled, build the web archive (WAR) file that will be deployed. This is accomplished by running Ant from the command line with an argument ("war") that tells it to build the WAR file.
```
C:\myprojects\vrlsapp> %ANT_HOME%\bin\ant war
```
Deploy the WAR file. This process varies depending on which Web container you are using, so we will concentrate here on Tomcat. Consult the documentation for your Web container for specific instructions.

In general, WAR files can be deployed to most J2EE Web containers by "dropping" them in the appropriate directory. If the container is properly configured, it will automatically expand the WAR file's contents into an appropriate place for deployment within the container.

Tomcat is no exception: dropping the WAR file into the webapps directory under the Tomcat root, even while Tomcat is running, will result in the WAR file being expanded and deployed. However, to ensure proper deployment, we encourage you to stop Tomcat and clear out the "vrls" directory (if it exists) before deploying the WAR file, and to restart Tomcat when you are done deploying.
```
C:\myprojects\vrlsapp> %TOMCAT_HOME%\bin\shutdown.bat

C:\myprojects\vrlsapp> rmdir %TOMCAT_HOME%\webapps\vrls /s /q

C:\myprojects\vrlsapp> copy vrls.war %TOMCAT_HOME%\webapps

C:\myprojects\vrlsapp> %TOMCAT_HOME%\bin\startup.bat
```
We provide an Ant target in the build.xml file called "deploy", which should work if you are using Tomcat 5.5 and installed Tomcat 5.5 in the default location. If you have changed any of the defaults, you may need to edit the build.xml file to reflect those changes. If you are unsure of how to do this, go through the list of manual steps described above.
```
C:\myprojects\vrlsapp> %ANT_HOME%\bin\ant deploy
```
Open the application in your web browser. If necessary, start or restart your application server. (Live deployment in Tomcat makes restart unnecessary as Tomcat will expand and deploy the WAR file if it is dropped into the webapps directory while Tomcat is running.) Then direct your web browser to http://localhost:8080/vrls, which will display a page describing the book and the associated application. Click on one of the "Try the app" links to use the application.

Debugging Tips

If you should experience problems getting the application to run:

Check your server error logs (found in %TOMCAT_HOME%\logs) if you are having trouble connecting to the database. This may give you insight into what the problem is.
If database connectivity problems persist in Tomcat, remove the "validationQuery" line in the context.xml file and then rebuild and redeploy the application. (Note that this validation query will only work once the application database tables have been populated, so make sure you have executed all the provided SQL scripts before attempting to connect to the database.)
When all else fails, go to Google and search for solutions to the problems you are seeing. Others have probably faced similar problems. For example, searching on "cannot load JDBC driver" plus "tomcat" and "mysql" recently helped us solve a nagging problem (that turned out to be a simple configuration error on our part).
Finally, feel free to contact the authors if you have any questions or problems regarding the application.