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

http://java.sun.com/javase/downloads/index.jsp

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

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 spring-framework-2.5.6-with-dependencies.zip

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.