Enterprise Java Logo

Web Application Case Study: AnimalSurvey

by Dr. Wenjie He

In this lecture, we study the code of AnimalSurvey. We mainly focus on the Ant build.xml script. directly.

Run Example AnimalSurvey2

  1. Download the source code AnimalSurvey2.zip. After you unzip the file and extract it to some directory, you get the AnimalSurvey2 folder. It is an Eclipse project folder.
  2. Import the project AnimalSurvey2 into the Eclipse. Select File ==> Import.... The Import windows opens. Expand the General node, and select the Existing Projects into Workspace.

  3. Click Next. In the new window, press the Browse... button to navigate to the directory AnimalSurvey2 you prepared above, click OK to load it. Check the box Copy projects into workspace, and click Finish. Then the project is loaded into the Eclipse.

    4. You would see the project tree in the Eclipse similar to the one below.

  4. Open the build.properties file in the Text Editor of Eclipse. (Right-click the build.properties node, select Open With ==> Text Editor. If you double-click the node, you may open it in a different editor.)
  5. Verify the following parameters:

    6. appserver.home    point to your Tomcat installation directory

    hsqldb.lib    point to your HSQLDB library location

    tomcat.manager.username    your username for the Tomcat manager account

    tomcat.manager.password    your password for the Tomcat manager account
  6. Open the Ant view. Select Window ==> Show View ==> Ant.
  7. Load the build.xml into the Ant view. Right-click anywhere inside the Ant view area, select Add Buildfiles.... In the Buildfile window, locate your build.xml file and click OK to load it. Expand the AnimalSurvey node, you would see all the Ant targets listed.

  8. Start the HSQLDB database server: double-click the dbserver node in the Ant view.
  9. Create tables: double-click the createTables node in the Ant view.
  10. Load data into the table: double-click the loadData node in the Ant view.
  11. View data in the table: double-click the printData node in the Ant view.
  12. Deploy the web application: double-click the deploy node in the Ant view.
  13. Start the Tomcat: double-click the startTomcat node in the Ant view.
  14. Run the web application: double-click the runweb node in the Ant view.
    15. You would see the AnimalSurvey web application is running in IE.

  15. Stop the Tomcat: double-click the stopTomcat node in the Ant view.
  16. Shut down the database: double-click the shutdownDB node in the Ant view. You shut down the animaldb database first. After that, since there is no database running in the HSQLDB database server, the server is automatically shut down.

Study Ant Scripts

1. Script for Build Properties build.properties

Code Listing: build.properties 
  
1.	# Ant properties for building the springapp
2.
3.	appserver.home=/JavaEE/Servers/Tomcat/apache-tomcat-5.5.26
4.	# for Tomcat 5 use $appserver.home}/server/lib
5.	# for Tomcat 6 use $appserver.home}/lib
6.	appserver.lib=${appserver.home}/server/lib
7.	appserver.bin=${appserver.home}/bin
8.	appserver.comlib=${appserver.home}/common/lib
9.	hsqldb.lib=/JavaEE/DBMS/hsqldb/lib
10.	hsqldb.dbfile=file:db/animaldb
11.	hsqldb.dbalias=animaldb
12.
13.	deploy.path=${appserver.home}/webapps
14.
15.	tomcat.manager.url=http://localhost:8080/manager
16.	tomcat.manager.username=tomcat
17.	tomcat.manager.password=javaee
18.
19.	db.driver=org.hsqldb.jdbcDriver
20.	db.url=jdbc:hsqldb:hsql://localhost/animaldb
21.	db.user=sa
22.	db.pw=
  1. (Line 3) Define appserver.home for your Tomcat installation directory.
  2. (Line 6) We need the JAR files in appserver.lib to run the Tomcat management tasks, such as install, reload, (see build.xml).
  3. (Line 7) We use appserver.bin to start and stop Tomcat.
  4. (Line 8) We use appserver.comlib for servlet-api.jar to compile servlets.
  5. (Line 9) We need hsqldb.lib to get hsqldb.jar. In this way, we do not need to copy hsqldb.jar into war\WEB-INF\lib of the AnimalSurvey.
  6. (Line 10) We define hsqldb.dbfile as the database file name that will be used when we start the HSQLDB database server. The reason why we use file:db/animaldb is that we want to put our database files animaldb.* into the db subdirectory of AnimalSurvey.
  7. (Line 11) We define hsqldb.dbalias as the alias of the database, which will be used for connecting the database in our Java source files.
  8. (Line 20) The alias of the database is used for the URL to connect the database.

2. The Ant Build Script build.xml

Code Listing: build.properties Line 1-24 
 
1.  <?xml version="1.0"?>
2.
3.  <project name="AnimalSurvey" basedir="." default="usage">
4.      <property file="build.properties"/>
5.
6.      <property name="src.dir" value="src"/>
7.      <property name="web.dir" value="war"/>
8.      <property name="build.dir" value="${web.dir}/WEB-INF/classes"/>
9.      <property name="name" value="AnimalSurvey"/>
10.     <property name="browser" location="C:/Program Files/Internet Explorer/iexplore.exe"/>
11.     <property name="webappurl" location="http://localhost:8080/${name}"/>
12.
13.     <path id="master-classpath">
14.        <fileset dir="${web.dir}/WEB-INF/lib">
15.           <include name="*.jar"/>
16.        </fileset>
17.        <!-- We need the servlet API classes: -->
18.        <!--  * for Tomcat 5/6 use servlet-api.jar -->
19.        <!--  * for other app servers - check the docs -->
20.        <fileset dir="${appserver.lib}">
21.           <include name="servlet*.jar"/>
22.        </fileset>
23.        <pathelement path="${build.dir}"/>
24.     </path>

  1. (Line 4) The file attribute of the property task specifies the location of the properties file to load. This line reads a set of properties from a file called build.properties.
  2. (Line 13-24) This block is called a path-like structure. It is a collection of resources in the form of files and directories. If later we want to refer to this collection of rescources of Line 14-23, we only need to use the value of the id attribute in Line 13.
  3. (Line 14-16) A FileSet specifies a group of files. The dir attribute provides the root of the directory tree of this FileSet. The include attribute specifies a comma- or space-separated list of patterns of files that must be included; all files are included when include is omitted.
  4. (Line 23) This line gives one rescource item in the path element. The path attribute of pathelement provides a colon- or semicolon-separated list of locations of files and directories. The pathelement element can also use the location attribute to specify a single file or directory relative to the project's base directory (or an absolute filename).

Code Listing: build.properties Line 25-53 
 
25.  <path id="hsqldb.lib.path">
26.	  <fileset dir="${hsqldb.lib}">
27.	    <include name="hsqldb.jar"/>
28.	  </fileset>
29.  </path>
30.	
31.  <path id="servlet.lib.path">
32.     <fileset dir="${appserver.comlib}">
33.	     <include name="servlet-api.jar"/>
34.     </fileset>
35.  </path>
36.
37.  <target name="usage">
38.     <echo message=""/>
39.     <echo message="${name} build file"/>
40.     <echo message="-----------------------------------"/>
41.     <echo message=""/>
42.     <echo message="Available targets are:"/>
43.     <echo message=""/>
44.     <echo message="build     --> Build the application"/>
45.     <echo message="deploy    --> Deploy application as directory"/>
46.     <echo message="deploywar --> Deploy application as a WAR file"/>
47.     <echo message="install   --> Install application in Tomcat"/>
48.     <echo message="reload    --> Reload application in Tomcat"/>
49.     <echo message="start     --> Start Tomcat application"/>
50.     <echo message="stop      --> Stop Tomcat application"/>
51.     <echo message="list      --> List Tomcat applications"/>
52.     <echo message=""/>
53.  </target>
  1. (Line 25-29) we define a reference for the HSQLDB JAR file hsqldb.jar, so that we do not need to physically copy hsqldb.jar into the war\WEB-INF\lib to save some space.
  2. (Line 31-35) we define a reference for the servlet-api.jar, so that we do not need to physically copy it into the war\WEB-INF\lib to save some space.

Code Listing: build.properties Line 54-98 
 
54.  <target name="build" description="Compile main source tree java files">
55.     <mkdir dir="${build.dir}"/>
56.     <javac destdir="${build.dir}" source="1.5" target="1.5" debug="true"
57.            deprecation="false" optimize="false" failonerror="true">
58.        <src path="${src.dir}"/>
59.           <classpath refid="servlet.lib.path"/>
60.     </javac>
61.  </target>
62.
63.  <target name="deploy" depends="build" description="Deploy application">
64.     <copy todir="${deploy.path}/${name}" preservelastmodified="true">
65.        <fileset dir="${web.dir}">
66.           <include name="**/*.*"/>
67.        </fileset>
68.     </copy>
69.     <copy todir="${deploy.path}/${name}/WEB-INF/lib" preservelastmodified="true">
70.        <fileset dir="${hsqldb.lib}">
71.    	    <include name="hsqldb.jar"/>
72.        </fileset>
73.     </copy>
74.  </target>
75.	
76.  <target name="copyhsqldblib" description="Copy HSQLDB JAR file temporarily into war">
77.	  <copy todir="${web.dir}/WEB-INF/lib" preservelastmodified="true">
78.	     <fileset dir="${hsqldb.lib}">
79.	        <include name="hsqldb.jar"/>
80.	     </fileset>
81.	  </copy>
82.  </target>
83.
84.  <target name="deploywar" depends="build,copyhsqldblib" 
85.          description="Deploy application as a WAR file">
86.     <war destfile="${name}.war"
87.          webxml="${web.dir}/WEB-INF/web.xml">
88.        <fileset dir="${web.dir}">
89.           <include name="**/*.*"/>
90.        </fileset>
91.     </war>
92.     <copy todir="${deploy.path}" preservelastmodified="true">
93.        <fileset dir=".">
94.           <include name="*.war"/>
95.        </fileset>
96.     </copy>
97.     <delete file="${web.dir}/WEB-INF/lib/hsqldb.jar"/>
98.  </target>

  1. (Line 56) The debug attribute indicates whether source should be compiled with debug information; defaults to off.
  2. (Line 57) The deprecation attribute indicates whether source should be compiled with deprecation information; defaults to off.
  3. (Line 57) The optimize attribute indicates whether source should be compiled with optimization; defaults to off.
  4. (Line 57) The failonerror attribute indicates whether compilation errors will fail the build; defaults to true.
  5. (Line 59) The classpath element with the attribute refid="servlet.lib.path" refers to the resource collection defined by the path element in Line 31.
  6. (Line 64) The copy task copies a file or resource collection to a new file or directory. By default, files are only copied if the source file is newer than the destination file, or when the destination file does not exist.
  7. (Line 64) The attribute preservelastmodified="true" of the copy task gives the copied files the same last modified time as the original source files.
  8. (Line 69-73) Directly copy the hsqldb.jar from its original location to the deployed location. In this way, we do not need to copy it to another preparation directory like war\WEB-INF\lib of AnimalSurvey.
  9. (Line 79) The target copyhsqldblib is used for the target deploywar. Since the WAR file is an archive file, we cannot copy any other file into it after it is packaged. So we use copyhsqldblib target to copy the file hsqldb.jar into the directory war\WEB-INF\lib of AnimalSurvey before our web application is packaged. After our web application is deployed, the file hsqldb.jar in war\WEB-INF\lib will be deleted to save some space.
  10. (Line 86) The war target packages our web application in a WAR file. It is an extension of the jar task with special treatment for files that should end up in the WEB-INF/lib, WEB-INF/classes or WEB-INF directories of the Web Application Archive.
  11. (Line 87) The webxml attribute of the war target specifies the deployment descriptor of our web application.
  12. (Line 97) The file attribute of the delete task specifies the file to be deleted. Note, when we use file attribute, only single file can be deleted. We cannot use it to delete more than one files.
  13. (Line 97) In order to delete more than one files using the delete task, we can do like this, 
    14.  
<delete>
   <fileset dir="." includes="**/*.*"/>
</delete>
  14. (Line 97) If you want to delete a directory, use the dir attribute instead of the file attribute.

Code Listing: build.properties Line 99-120 
  
99.	<target name="dbserver" description="Runs HSQLDB database server">
100.	      <java classname="org.hsqldb.Server"
101.	            fork="yes">
102.	         <classpath refid="hsqldb.lib.path"/>
103.	         <arg value="-database.0"/>
104.	      	 <arg value="${hsqldb.dbfile}"/>
105.	      	 <arg value="-dbname.0"/>
106.	      	 <arg value="${hsqldb.dbalias}"/>
107.	      </java>
108.	</target>
109.
110.  <target name="createTables">
111.      <echo message="CREATE TABLES USING: ${db.driver} ${db.url}"/>
112.      <sql driver="${db.driver}"
113.         url="${db.url}"
114.         userid="${db.user}"
115.         password="${db.pw}"
116.         onerror="continue"
117.         src="db/create_table.sql">  
118.        <classpath refid="hsqldb.lib.path"/>
119.      </sql> 
120   </target>

  1. (Line 99-108) This target is created to run the HSQLDB server. The original command to start the HSQLDB server is a Java command running at a command window as follows, 
    2.  
java -classpath ..\war\WEB-INF\lib\hsqldb.jar org.hsqldb.Server 
     -database.0 file:db/animaldb -dbname.0 animaldb
    (The above command should be in one line.) Line 100-107 translate the above command into an Ant task.
  2. (Line 112-119) The sql task executes a series of SQL statements via JDBC to a database.
  3. (Line 112) The driver attribute of sql specifies the Java class name of the jdbc driver of the database.
  4. (Line 113) The url attribute of sql specifies the database connection url.
  5. (Line 116) The onerror attribute specifies how to proceed when an error occurs during the execution of one of the statements.
  6. (Line 117) The src attribute of sql specifies the SQL script that contains a series of SQL statements.
  7. (Line 118) The classpath element inside the sql task specifies the location of the JAR file for the HSQLDB database driver.

Code Listing: build.properties Line 121-188 
  
121.    <target name="dropTables">
122.        <echo message="DROP TABLES USING: ${db.driver} ${db.url}"/>
123.        <sql driver="${db.driver}"
124.             url="${db.url}"
125.             userid="${db.user}"
126.             password="${db.pw}"
127.             onerror="continue">  
128.            <classpath refid="hsqldb.lib.path"/>
129.
130.        DROP TABLE surveyresults;
131.
132.        </sql> 
133.    </target>
134.
135.    <target name="loadData">
136.        <echo message="LOAD DATA USING: ${db.driver} ${db.url}"/>
137.        <sql driver="${db.driver}"
138.             url="${db.url}"
139.             userid="${db.user}"
140.             password="${db.pw}"
141.             onerror="continue"
142.             src="db/load_data.sql">  
143.            <classpath refid="hsqldb.lib.path"/>
144.        </sql> 
145.    </target>
146.
147.    <target name="printData">
148.        <echo message="PRINT DATA USING: ${db.driver} ${db.url}"/>
149.        <sql driver="${db.driver}"
150.             url="${db.url}"
151.             userid="${db.user}"
152.             password="${db.pw}"
153.             onerror="continue"
154.             print="true">  
155.            <classpath refid="hsqldb.lib.path"/>
156.
157.        SELECT * FROM surveyresults;
158.
159.        </sql> 
160.    </target>
161.
162.    <target name="clearData">
163.        <echo message="CLEAR DATA USING: ${db.driver} ${db.url}"/>
164.        <sql driver="${db.driver}"
165.             url="${db.url}"
166.             userid="${db.user}"
167.             password="${db.pw}"
168.             onerror="continue">  
169.            <classpath refid="hsqldb.lib.path"/>
170.
171.        DELETE FROM surveyresults;
172.
173.        </sql> 
174.    </target>
175.
176.    <target name="shutdownDb">
177.        <echo message="SHUT DOWN DATABASE USING: ${db.driver} ${db.url}"/>
178.        <sql driver="${db.driver}"
179.             url="${db.url}"
180.             userid="${db.user}"
181.             password="${db.pw}"
182.             onerror="continue">  
183.            <classpath refid="hsqldb.lib.path"/>
184.
185.        SHUTDOWN;
186.
187.        </sql> 
188.    </target>

  1. (Line 130,157,171,185) These four lines use the inline SQL statements inside the sql task.
  2. (Line 176) The shutdownDb stops the database specified by the url attribute, not the database server.
  3. There is no specific command in HSQLDB to shut down the database server. When all the databases are shut down, the database server is shut down automatically.

Code Listing: build.properties Line 189-209 
  
189.    <path id="catalina-ant-classpath">
190.        <!-- We need the Catalina jars for Tomcat -->
191.        <!--  * for other app servers - check the docs -->
192.        <fileset dir="${appserver.lib}">
193.            <include name="catalina-ant.jar"/>
194.        </fileset>
193.    </path>
194.
195.    <taskdef name="install" classname="org.apache.catalina.ant.InstallTask">
196.        <classpath refid="catalina-ant-classpath"/>
197.    </taskdef>
198.    <taskdef name="reload" classname="org.apache.catalina.ant.ReloadTask">
199.        <classpath refid="catalina-ant-classpath"/>
200.    </taskdef>
201.    <taskdef name="list" classname="org.apache.catalina.ant.ListTask">
202.        <classpath refid="catalina-ant-classpath"/>
203.    </taskdef>
204.    <taskdef name="start" classname="org.apache.catalina.ant.StartTask">
205.        <classpath refid="catalina-ant-classpath"/>
206.    </taskdef>
207.    <taskdef name="stop" classname="org.apache.catalina.ant.StopTask">
208.        <classpath refid="catalina-ant-classpath"/>
209.    </taskdef>

  1. (Line 195-209) These lines define some commonly used Tomcat tasks that help manage the web applications.

Code Listing: build.properties Line 210-266 
  
210.	<target name="startTomcat">
211.	  <exec executable="cmd">
212.	    <arg value="/c"/>
213.	    <arg value="${appserver.bin}/startup.bat"/>
214.	  </exec>
215.	</target>
216.
217.	<target name="stopTomcat">
218.	  <exec executable="cmd">
219.	    <arg value="/c"/>
220.	    <arg value="${appserver.bin}/shutdown.bat"/>
221.	  </exec>
222.	</target>
223.
224.    <target name="install" description="Install application in Tomcat">
225.        <install url="${tomcat.manager.url}"
226.                 username="${tomcat.manager.username}"
227.                 password="${tomcat.manager.password}"
228.                 path="/${name}"
229.                 war="${name}"/>
230.    </target>
231.
232.    <target name="reload" description="Reload application in Tomcat">
233.        <reload url="${tomcat.manager.url}"
234.                 username="${tomcat.manager.username}"
235.                 password="${tomcat.manager.password}"
236.                 path="/${name}"/>
237.    </target>
238.
239.    <target name="start" description="Start Tomcat application">
240.        <start url="${tomcat.manager.url}"
241.                 username="${tomcat.manager.username}"
242.                 password="${tomcat.manager.password}"
243.                 path="/${name}"/>
244.    </target>
245.
246.    <target name="stop" description="Stop Tomcat application">
247.        <stop url="${tomcat.manager.url}"
248.                 username="${tomcat.manager.username}"
249.                 password="${tomcat.manager.password}"
250.                 path="/${name}"/>
251.    </target>
252.
253.    <target name="list" description="List Tomcat applications">
254.        <list url="${tomcat.manager.url}"
255.                 username="${tomcat.manager.username}"
256.                 password="${tomcat.manager.password}"/>
257.    </target>
258.	
259.	<target name="runweb" depends="deploy">
260.		<exec executable="cmd">
261.		   <arg value="/c"/>
262.		   <arg value="runwebapp.bat"/>
263.		</exec>
264.	</target>
265.
266. </project>

  1. (Line 210-215) The target startTomcat starts the Tomcat server inside Ant. We just run the startup.bat script of Tomcat. We cannot run the .bat files directly in Ant as we run .exe files. We need to run the windows cmd command with the /c switch.

==========The End==========