Environment Setup and Basic Tomcat Application

Developing Web Applications
with OpenRules and Tomcat

Part 1 – Environment Setup and Basic Tomcat Application

"I am not going to cover a lot of background information or theory in this document -- there are plenty of books available that covers this in depth. Instead we will dive right into developing the application." Thomas Risberg.

Introduction

This is the first part of a step-by-step account of how to setup an environment and develop a basic web application from scratch using Tomcat and OpenRules. This application and setup will be used as a starting point for different web application configurations using OpenRules and different application servers and development frameworks.

We will base our description on the step-by-step instructions written by Thomas Risberg and oriented to the Spring framework. We gratefully acknowledge Thomas Risberg's copyright and recommend readers to read his original instructions. While we try to follow his presentation style and configuration decisions, we made many changes by removing references to Spring framework and JSTL (not needed for this basic application).

Prerequisites

Java SDK (using version 1.4.2 or higher)
Ant (using version 1.6.2)
Apache Tomcat (using version 5.5.17 or higher)

You should also be reasonably comfortable using the above software.

Step 1 – development directory

We are going to need a place to keep all the source and other files we will be creating, so let's create a directory and name it 'hello.tomcat'. You can place this directory in your home folder or in some other location. Inside this directory we create a 'src' directory to hold all Java source files. Then we create another directory that we name 'war'. This directory will hold everything that should go into the WAR file, that we would use to deploy our application. All source files other than Java source, like JSPs and configuration files, belongs in this directory.

Step 2 – index.jsp

We will start by creating a JSP page named 'index.jsp' in the war directory. This is the entry point for our application.

hello.tomcat/war/index.jsp

<html>
<head><title>Example :: Hello Web Application</title></head>
<body>
<h1>Example - Hello Application</h1>
<p>This is my test.</p>
</body>
</html>

Just to have a complete web application, we create a web.xml in a WEB-INF directory that we create under the war directory.

hello.tomcat/war/WEB-INF/web.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN' 'http://java.sun.com/dtd/web-app_2_3.dtd'>

<web-app>

</web-app>

Step 3 – deploying the application to Tomcat

Next, we write an Ant build script that we are going to use throughout this document. There are tasks for building and deploying the application. A separate build script contains the app server specific tasks There are also tasks for controlling the application under Tomcat.

hello.tomcat/build.xml

<?xml version="1.0"?>

<project name="openrules.build" basedir="." default="usage">
    <property file="build.properties"/>

    <property name="src.dir" value="src"/>
    <property name="web.dir" value="war"/>
    <property name="build.dir" value="${web.dir}/WEB-INF/classes"/>
    <property name="name" value="${war.name}"/>

    <path id="master-classpath">
        <fileset dir="${web.dir}/WEB-INF/lib">
            <include name="*.jar"/>
        </fileset>
        <!-- We need the servlet API classes:        -->
        <!--   for Tomcat 4.1 use servlet.jar        -->
        <!--   for Tomcat 5.0 use servlet-api.jar    -->
        <!--   for Other app server - check the docs -->
        <fileset dir="${appserver.home}/common/lib">
            <include name="servlet*.jar"/>
        </fileset>
        <pathelement path="${build.dir}"/>
    </path>

    <target name="usage">
        <echo message=""/>
        <echo message="${name} build file"/>
        <echo message="-----------------------------------"/>
        <echo message=""/>
        <echo message="Available targets are:"/>
        <echo message=""/>
        <echo message="build     --> Build the application"/>
        <echo message="deploy    --> Deploy application as directory"/>
        <echo message="deploywar --> Deploy application as a WAR file"/>
        <echo message="install   --> Install application in Tomcat"/>
        <echo message="reload    --> Reload application in Tomcat"/>
        <echo message="start     --> Start Tomcat application"/>
        <echo message="stop      --> Stop Tomcat application"/>
        <echo message="list      --> List Tomcat applications"/>
        <echo message=""/>
    </target>

    <target name="build" description="Compile main source tree java files">
        <mkdir dir="${build.dir}"/>
        <javac destdir="${build.dir}" debug="true"
               deprecation="false" optimize="false" failonerror="true">
            <src path="${src.dir}"/>
            <classpath refid="master-classpath"/>
        </javac>
    </target>

    <target name="deploy" depends="build" description="Deploy application">
        <copy todir="${deploy.path}/${name}" preservelastmodified="true">
            <fileset dir="${web.dir}">
                <include name="**/*.*"/>
            </fileset>
        </copy>
    </target>

    <target name="deploywar" depends="build" description="Deploy application as a WAR file">
        <war destfile="${name}.war"
             webxml="${web.dir}/WEB-INF/web.xml">
            <fileset dir="${web.dir}">
                <include name="**/*.*"/>
            </fileset>
        </war>
        <copy todir="${deploy.path}" preservelastmodified="true">
            <fileset dir=".">
                <include name="*.war"/>
            </fileset>
        </copy>
    </target>

<!-- ============================================================== -->
<!-- Tomcat tasks - remove these if you don't have Tomcat installed -->
<!-- ============================================================== -->

    <taskdef name="install" classname="org.apache.catalina.ant.InstallTask">
        <classpath>
            <path location="${appserver.home}/server/lib/catalina-ant.jar"/>
        </classpath>
    </taskdef>
    <taskdef name="reload" classname="org.apache.catalina.ant.ReloadTask">
        <classpath>
            <path location="${appserver.home}/server/lib/catalina-ant.jar"/>
        </classpath>
    </taskdef>
    <taskdef name="list" classname="org.apache.catalina.ant.ListTask">
        <classpath>
            <path location="${appserver.home}/server/lib/catalina-ant.jar"/>
        </classpath>
    </taskdef>
    <taskdef name="start" classname="org.apache.catalina.ant.StartTask">
        <classpath>
            <path location="${appserver.home}/server/lib/catalina-ant.jar"/>
        </classpath>
    </taskdef>
    <taskdef name="stop" classname="org.apache.catalina.ant.StopTask">
        <classpath>
            <path location="${appserver.home}/server/lib/catalina-ant.jar"/>
        </classpath>
    </taskdef>

    <target name="install" description="Install application in Tomcat">
        <install url="${tomcat.manager.url}"
                 username="${tomcat.manager.username}"
                 password="${tomcat.manager.password}"
                 path="/${name}"
                 war="${name}"/>
    </target>

    <target name="reload" description="Reload application in Tomcat">
        <reload url="${tomcat.manager.url}"
                 username="${tomcat.manager.username}"
                 password="${tomcat.manager.password}"
                 path="/${name}"/>
    </target>

    <target name="start" description="Start Tomcat application">
        <start url="${tomcat.manager.url}"
                 username="${tomcat.manager.username}"
                 password="${tomcat.manager.password}"
                 path="/${name}"/>
    </target>

    <target name="stop" description="Stop Tomcat application">
        <stop url="${tomcat.manager.url}"
                 username="${tomcat.manager.username}"
                 password="${tomcat.manager.password}"
                 path="/${name}"/>
    </target>

    <target name="list" description="List Tomcat applications">
        <list url="${tomcat.manager.url}"
                 username="${tomcat.manager.username}"
                 password="${tomcat.manager.password}"/>
    </target>

<!-- End Tomcat tasks -->

</project>

This script now contains all the targets that we are going to need to make our development efforts easier. We are not going to cover this script in detail since most if not all of it is pretty much standard Ant and Tomcat stuff. You can just copy the above build file and put it at the root of your development directory tree. We also need a build.properties file that you should customize to match your server installation. This file belongs in the same directory as the build.xml file.

hello.tomcat/build.properties

war.name=hello.tomcat

appserver.home=C:/apache-tomcat-5.5.17

deploy.path=${appserver.home}/webapps

tomcat.manager.url=http://localhost:8080/manager
tomcat.manager.username=admin
tomcat.manager.password=tomcat

For example, on Windows, if your tomcat has been installed at c:/apache-tomcat-5.5.17, you may define
appserver.home=c:/apache-tomcat-5.5.17
If you are on a system where you are not the owner of the Tomcat install, then the Tomcat owner must either grant you full access to the webapps directory or the owner must create a new directory named 'hello.tomcat' in the 'webapps' directory of the Tomcat installation, and also give you full rights to deploy to this newly created directory. On Linux you may run the command chmod a+rwx hello.tomcat to give everybody full rights to this directory.

If you are using a different web application server, then you can remove the Tomcat specific tasks at the end of the build script. You will have to rely on your server's hot deploy feature, or you will have to stop and start your application manually.

Now we run Ant to make sure that everything is working OK. You should have your current directory set to the 'hello.tomcat' directory.

Buildfile: build.xml
 
usage:
 
     [echo] helloapp build file
     [echo] -----------------------------------
 
     [echo] Available targets are:
 
     [echo] build     --> Build the application
     [echo] deploy    --> Deploy application as directory
     [echo] deploywar --> Deploy application as a WAR file
     [echo] install   --> Install application in Tomcat
     [echo] reload    --> Reload application in Tomcat
     [echo] start     --> Start Tomcat application
     [echo] stop      --> Stop Tomcat application
     [echo] list      --> List Tomcat applications
 
 
BUILD SUCCESSFUL
Total time: 2 seconds

Last action here is to do the actual deployment. Just run Ant and specify 'deploy' or 'deploywar' as the target.

Buildfile: build.xml
 
build:
    [mkdir] Created dir: /hello.tomcat/war/WEB-INF/classes

deploy:
     [copy] Copying 2 files to /apache-tomcat-5.5.17/webapps/hello.tomcat
BUILD SUCCESSFUL
Total time: 2 seconds

To simplify the future use of OpenRules, you can make the following simple changes:

1) Added the "manager" role to the user "tomcat" to allow web application deployment. Tomcat Server allows a web application to establish connection as a Manager Application (responsible for remote Web Application deployment). So, you can add the word "manager" in file 'conf/tomcat-users.xml':

2) You may use the user "tomcat" by making changes in 'build.properties' file:

tomcat.manager.username=tomcat
tomcat.manager.password=tomcat

Step 4 – Test the application

Let's just quickly start Tomcat and make sure that we can access the application. Use the 'list' task from our build file to see if Tomcat has picked up the new application.

Buildfile: build.xml
 
list:
     [list] OK - Listed applications for virtual host localhost

     [list] /admin:running:0:/apache-tomcat-5.5.17/server/webapps/admin

     [list] /webdav:running:0:/apache-tomcat-5.5.17/webapps/webdav

     [list] /servlets-examples:running:0:/apache-tomcat-5.5.17/webapps/servlets-examples

     [list] /helloapp:running:0:/apache-tomcat-5.5.17/webapps/hello.tomcat

     [list] /jsp-examples:running:0:/apache-tomcat-5.5.17/webapps/jsp-examples

     [list] /balancer:running:0:balancer

     [list] /tomcat-docs:running:0:/apache-tomcat-5.5.17/webapps/tomcat-docs

     [list] /:running:0:/apache-tomcat-5.5.17/webapps/ROOT

     [list] /manager:running:0:/apache-tomcat-5.5.17/server/webapps/manager
 
 
BUILD SUCCESSFUL
Total time: 1 second

If it is not listed, use the 'install' task to get the application installed in Tomcat.

Buildfile: build.xml
 
install:
  [install] OK - Installed application at context path /hello.tomcat 
 
BUILD SUCCESSFUL
Total time: 2 seconds

Now open a browser and browse to http://localhost:8080/hello.tomcat/index.jsp

To simplify the future launches of a browser, we will add the following 'run.html' file to the project directory:

<h2> OpenRules </h2>
<h3> Tomcat-based Basic JSP Web Application</h3>
<ul>
<li>Business logic - Java</li>
<li>Views - JSP</li>
</ul>
<a href="http://localhost:8080/hello.tomcat/index.jsp"> 
Run Hello Customer Example</a>

Summary

We created a development environment with Ant build files.
We setup a trivial web application that is used only to test our setup.
So far, our application hello.tomcat is extremely basic. But the whole setup works and we are now ready to add real functionality.

Back Implementing HelloCustomer Application using JSP and Java