Saturday, December 20, 2008

How to run the Spring Petclinic Sample Web Application

This week, I was asked to introduce a co-worker to some of the main Programming concepts behind Java Web Applications. This person was very familiar with DotNet, but had not touched Java in many years.

Like most programmers, he didn't want to read books...he wanted to get his hands on sample code as quickly as possible.

Rather than downloading the official Java EE Servers and exploring their sample code, I suggested he start looking at Java, Spring, and a lighter-weight Java Web Server such as Apache Tomcat.

Spring is NOT part of the official Java release from Sun. However, it is one of the leading (if not the leading) platforms to build and run enterprise Java applications.

Apache Tomcat is one of the leading (if not the leading) Java Web Servers (technically its a Java Servlet container). Unlike other industry giants such as BEA WebLogic ($expensive$), or IBM WebSphere($expensive$), Apache Tomcat (FREE) is not a full-blown Java EE Server and does not support the entire specification. That doesn't matter much though because developers have found it to be more than powerful enough to address a significant portion of the Enterprise Application problems out there. Especially when Apache Tomcat is paired with Spring.

So that's the set-up. There are more than enough documents out there on the Web which give detailed information about Java, Spring, and Tomcat. What I couldn't find for him is a straight-forward step-by-step guide on how to get these samples working for a Java-newbie. So here are my notes to him!

Before starting - you will need to download and install 3 things. A JDK (Java Development Kit), Apache Ant (one of the most widely used command-line build tools...very analogous to 'make' in the C/C++ world), and Apache Tomcat (the Java Servlet Container):

  • Java JDK download of 1.5 or higher


    • I downloaded "Java SE Development Kit 6u12"

    • After installing, add the JDK's "bin" sub-directory to your User or System Path

    • Test the installation!  Open a new Command-Prompt Window

    • Type "java -version"

  •  Download and Install Apache Ant 1.6 or higher - Command-Line Build Tool.  Not required for Java, but it's the most widely-used Build Tool


    • I downloaded Ant 1.7.1 ( )

    • Unzip this file to a location of your choice

    • Add Ant's "bin" sub-directory to your User or System Path

    • Test the installation!  Open a new Command-Prompt Window

    • Type "ant -version"

  • Download and install a Java Web Server.  I'd recommend Tomcat


    • I downloaded 6.0.18 under Binary Distributions / CORE / zip (

    • Unzip this file to a location of your choice

    • Open a command-prompt, and Start-Up Tomcat by running "bin/startup.bat"

    • Open a web-browser and visit this URI: "http://localhost:8080/".  If Java and Tomcat are installed properly, you will see the Apache Tomcat Page!

We're almost there, now we have to download Spring (which will contain the sample PetClinic application)

  • Download

  • Unzip everything - you will get a directory called "spring-framework-2.5.6"

  • Look in the directory samples/petclinic

    • in this directory, there is a readme.txt file.  That gives instructions on how to build the sample

    • Type "warfile" from the command-line to run warfile.bat

    • If all goes well, you should see the message "BUILD SUCCESSFUL"

  • In the directory "spring-framework-2.5.6/samples/petclinic/dist" you should now find a file called "petclinic.war".  this is the Web Archive - it contains the entire PetClinic Application.  This is the file that should be deployed to your Web Server.

  • Since the PetClinic sample needs a working database, the Spring developers have kindly provided a small java database ready-to-go. You can Start-Up the pet clinic database by running this file

    • spring-framework-2.5.6/samples/petclinic/db/hsqldb/server.bat

  • Copy the petclinic WAR file to the Tomcat Webapps directory

    • Copy spring-framework-2.5.6/samples/petclinic/dist/petclinic.war

    • to this directory: apache-tomcat-6.0.18/webapps

    • About a second after copying the file, the WAR file will auto-deploy and you will see a new directory called apache-tomcat-6.0.18/webapps/petclinic

  • The application is now deployed. 

  • Try to visit this URI:  "http://localhost:8080/petclinic"

This should be all you need to do to make Java, Apache Ant, Apache Tomcat, and Spring run on a machine that never had any of these installed before.


Anonymous said...

Great Francis... :) I'm new with Java and that help's me.. I've download the code for v3.0 m.2, If you have any tip for build that and debug with eclipse it will be nice.

Anonymous said...

Very Good tutorial. Thank you.

Yashodhara said...

Thank you so much for the detailed information. Its been really helpful to start with.

Chad said...

I realize this was created 4 years ago, but it helped me a lot. Thanks again very much.