Test Driving the 'ZkFoodToGo' Example Application

Author
Simon Massey, Technical Lead, Marsh

Date
January 14, 2007

Version
Applicable to ZK 3.0.5 and later.

Introduction

How would you build a real database driven application using ZK? There are many possible solutions to this question. This article introduces the "ZkFoodToGo" example application that demonstrates one approach. The source code is available on zk.forge

"Food To Go" is a fictional fast food ordering system described by Chris Richardson in his book POJOs In Action. The book makes extensive use of Spring, JUnit and mock objects to demonstrate three alternative ORM frameworks: Hibernate, JDO and iBatis. The sample code that accompanies the book is available under the Apache 2.0 http://www.apache.org/licenses/ licence]. It comprises of mock object JUnit tests demonstrating POJO design patterns and ORM best practices. The book does not supply a user interface nor a complete set of application Use Cases. To create a small but complete web application some simple methods were added to the persistence code to support the screens. At the time of writing this article only the Hibernate implementation of the new methods have been completed

ZkFoodToGo uses a POJO domain model, event driven MVC, Spring (IoV pattern), a POJO Facade (with an AOP transaction manager) and Hibernate. The application architecture is well documented both on the ZK wiki and within the book

Prerequisites

The source code of the sample application is hosted on ZK.Forge and is built using Maven2. To access the source code you will need a Subversion client (I recommend TortoiseSVN for Windows and Subclipse for Eclipse). To build the source code you will need to install Maven

Building And Running The Application

You may skip this section by downloading the war file from this page . The following instructions build the application from a command-line usng Maven. They assume you are familiar with either bash on Linux or cmd.exe on Windows and that the Maven bin folder has been added to your PATH environment variable:

1. Checkout the zk.forge source code from https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/foodToGo using your favorite Subversion client

2. Open a command shell and change directory to foodToGo/dist/pia

3. Extract the FoodToGo source code zip file pia-zk-1.zip then change directory into the extracted folder pia-zk-1

4. Build the FoodToGo code from the book with the command mvn -Dmaven.test.skip=true install

5. Change directory up to foodToGo

6. Build the ZkFoodToGo webapp with the command mvn install

7. Run the web application with the command mvn jetty:run

8. Point your browser at http://localhost:8080/ZkFoodToGo

Jetty will remain running until you stop it with ctrl+c

Using The Application

Figure 1 is a screenshot of the application with an empty database:

Figure 1: The application with an empty database

To create a new restaurant enter a name (e.g. "Pizza To Go"), select a restaurant type (e.g. "Pizza"), then click on "Add Menu Item" to setup the menu of the restaurant. When you have input several menu items click on the "Save Restaurant" button. To create further restaurants click on the "New" button and repeat the process

Figure 2 shows the application after inputting some data into the database:

Figure 2: The application with data

Changing The Database Configuring

You do not need to setup a database to run the application. It will create it's own Hypersonic database by default. When the application is first started Hypersonic will create it's own data storage file. Hibernate will then automatically create all of the necessary database tables when it first encounters the empty database. This behaviour is controlled with the setting hibernate.hbm2ddl.auto within applicationContext.xml

After you have successfully built and deployed the default Hypersonic configuration you may wish to switch to a database such as Oracle, MySQL or SQLServer. The basic steps are to do this are:

1. Edit foodToGo/src/main/webapp/WEB-INF/applicationContext.xml

2. Change the hibernate.dialect setting to be the dialect of your database

3. Change the DataSource settings to reference your JDBC driver, URL, username and password

4. Place the JDBC drive jar where the web application can load it. One simple (but less than optimal) approach is to place the JDBC drive into Servlet container classpath

If you don't like the tables that Hibernate creates then create your own and change the the .hbm.xml mappings files named in applicationContext.xml

Developing And Debugging With Eclipse

Maven has good support for Eclipse. Start Eclipse and choose 'File > Switch Workspace...' Select a new folder to place the workspace (e.g. C:\eclipse\ZkFoodToGo) as shown in Figure 3:

Figure 3: Create A New Workspace

At the command-line where you built the application configure the classpath for Eclipse and generate the project files with the following Maven commands:

1. Add the project dependencies in the workspace with "mvn -Declipse.workspace=C:\eclipse\ZkFoodToGo eclipse:add-maven-repo" using the path of your workspace

2. Create the eclipse project file with "mvn eclipse:eclipse"

Within Eclipse switch workspace to the same folder to pick-up the new settings created by Maven. Now import the project files created by Maven with ' File > Import... ' and choose ' General > Existing Projects into Workstation ' as shown in Figure 4:

Figure 4: Eclipse Import

Then use the ' Browse... ' button to locate the foodToGo folder and click ' Finish ' as shown in Figure 5:

Figure 5: Locating The Maven Project

The ZkFoodToGo project will be loaded into the ' Package Explorer ' on the left. Expand the project to locate the Java code under src/main/java as shown in Figure 6:

Figure 6: Eclipse Java Project

The FoodToGo back-end code extracted and built from the zip file under foodToGo/dist/pia ships as a number of maven projects. The most significant project is ' pia-ch-03-domain-model ' which is the POJO domain model. I recommend that at the commandline where you built the project you change directory into foodToGo/dist/pia/pia-ch-03-domain-model and repeat the steps above to import this project into Eclipse

Next configure Maven to build the project ZkFoodToGo project. Open one of the java files in the project then select from the top menu bar ' Project > Properties ' and select ' Builders' then click ' New ...' and ' Program '. Then configure the settings shown in Figure 7:

1. Location: Use 'Browse File System...' to locate either mvn.bat (Windows) or mvn (Linux) in the bin folder of your Maven install

2. Working Directory: Use 'Browse Workspace...' and except the default location ZkFoodToGo

3. Arguments: Enter 'clean install' (N.B. You could also specify '--offline clean install' to build faster but the offline option may cause the build to fail if the pom.xml is changed either manually or during a Subversion update)

Figure 7: Eclipse Maven Builder

Now when you change the Java code and press " Ctrl+b " to build the project Eclipse it will launch Maven and rebuild the war file

To debug the application we can configure Eclipse to launch jetty via Maven. Within Eclipse choose ' Run > Debug... ' from the menu bar. Right-click on ' Java Application ' and select ' New '. Figure 8 shows the following settings to configure on the Main tab:

1. Name: "jetty"

2. Project: Use 'Browse...' to select the ZKFoodToGo project

3. Main class: "org.codehaus.classworlds.Launcher"

Figure 8: Debug Main Tab

Figure 9 shows the following settings to configure on the Arguments tab:

1. Program Argument: "jetty:run"

2. VM Arguments: "-Dclassworlds.conf=C:\opt\maven-2.0.4\bin\m2.conf -Dmaven.home=C:\opt\maven-2.0.4" replacing "C:\opt\maven-2.0.4\" with the path to your Maven install on your workstation

Figure 9: Debug Arguments Tab

Figure 10 shows the following settings to configure on the Classpath tab:

Select 'User Entries' then press 'Add External JARs...'. Browse to your Maven install and select core/boot/classworlds-1.1.jar

Figure 10: Debug Classpath Tab

Now press the ' Apply ' button then the ' Debug ' button. You can now set break points within Eclipse to debug the application.

Conclusion

ZkFoodToGo is a small but realistic example application using ZK. The purpose of the application is to provide a well documented application using ZK, POJO best practices, Spring, ORM and a database. The project is easy to build using Maven. It will automatically deploy a pure Java database but the configuration can be changed to use any database server. The project can also download and deploy to the Jetty Servlet container with a single command. The back-end to the application was taken "off the shelf" from the book POJOs In Action with trivial modifications. We invite the developer community to contribute to the code base so that it may follow ZK best practices as they evolve

Credits

I would like to thank the following people:

1. Chris Richardson - for his excellent book POJOs In Action and sample code

2. Friends and colleagues at Marsh that have framed my thoughts whilst working with ZK - Rathna Muthukumar, Julian Gosnell, David Birch and Ged Roberts

Simon Massey is a Technical Lead working for Marsh (London, UK). He is also the host deveoper of the ZKFoodToGo project for ZK.forge .

Copyright © Simon Massey. This article is licensed under GNU Free Documentation License.