Howto: Getting the Spring Framework running on Mac OS X

This describes my experiences getting the Spring Framework running on Mac 10.2.6.

For this example I used Tomcat since it is the reference implementation for Java servlets. The first part of this Howto deals with getting Tomcat running; the second deals with running the petclinic demo from the Spring Framework.

Download Tomcat from http://jakarta.apache.org/tomcat/ as a zip file and save it. In my case the name of the files was tomcat-4.1.24.zip. Don't let Stuffit Expander expand it because the archive contains long filenames. Instead, open a Terminal window. Navigate to the directory you downloaded the archive to (for example, type cd Desktop if you saved it to the desktop). Now we'll have to unzip it from the command line:

unzip tomcat-4.1.24.zip

I like to keep programs in my /Applications directory, so I used the Finder to move the jakarta-tomcat-4.1.24 folder into my Applications folder. Then, in the Terminal again, I typed

ln -s /Applications/jakarta-tomcat-4.1.24 /Applications/tomcat

That creates a symlink, which is like an alias. This way I can always refer to Tomcat as /Applications/tomcat, even when a new version of Tomcat comes out.

Tomcat needs to have some environment variables set. I used the instructions here to create an environment.plist file in a .MacOSX directory in my home directory. My environment.plist looks like this when edited in the Property List Editor:

Note the presence of CATALINA_HOME.

I made two AppleScripts using Script Editor (/Applications/AppleScript/Script Editor) as follows:

Then I saved the scripts as an application and checked the Never Show Startup Screen box. The result? Now I can start and stop Tomcat by double-clicking the appropriate icon:

Now it's time to click the Start Tomcat AppleScript and Tomcat will start on port 8080. Point your web browser to http://127.0.0.1:8080/ and you should see Tomcat's welcome screen.

The layout of files in your /Applications/tomcat directory should look like this:

We want to use the Tomcat Manager, so we'll need to give ourselves access. We do that by editing the tomcat-users.xml file in Tomcat's conf directory. You could double-click the file and Mac OS X will open it in the Properties Editor, but I prefer to edit xml files in a text editor. I use BBEdit, so I selected the tomcat-users.xml file in the Finder and chose Get Info from the File menu. I opened the Open With dropdown, chose BBEdit as the program to open this xml file, and while I was there I clicked the Change All button so that from now on all my xml files will open in BBEdit. That keeps me from having to drag them to the BBEdit icon in the Dock. If you don't have BBEdit, you could use TextEdit instead (just make sure to change from TextEdit's default RTF to plain text in TextEdit's Preferences).

I edited the tomcat-users.xml file by adding the following entry:

<user username="john" password="tommycat" roles="admin,manager"/>

Now, after restarting Tomcat, I have access to the Tomcat Manager application to show me the status of each running Tomcat Application.

All right, Tomcat is running and it's time to install Spring. I downloaded Spring from http://www.springframework.org/ and poked around. The petclinic demo in the samples directory looked interesting.

Here's me building a war file of the petclinic demo for deployment with Tomcat (note that I have Apache ant installed - that's not covered in this Howto):

cd /Applications/springframework/samples/petclinic/
ant build


Buildfile: build.xml

build:
    [mkdir] Created dir: /Applications/springframework/samples/petclinic/.classes
    [javac] Compiling 25 source files to /Applications/springframework/samples/petclinic/.classes
    [mkdir] Created dir: /Applications/springframework/samples/petclinic/war/WEB-INF/lib
      [jar] Building jar: /Applications/springframework/samples/petclinic/war/WEB-INF/lib/petclinic.jar
     [copy] Copying 7 files to /Applications/springframework/samples/petclinic/war/WEB-INF/lib

BUILD SUCCESSFUL
Total time: 3 seconds

ant warfile

Buildfile: build.xml

build:

docs:
    [mkdir] Created dir: /Applications/springframework/samples/petclinic/war/docs
  [javadoc] Generating Javadoc
  [javadoc] Javadoc execution
  [javadoc] Loading source files for package petclinic...
  [javadoc] Loading source files for package petclinic.dao...
  [javadoc] Loading source files for package petclinic.validation...
  [javadoc] Loading source files for package petclinic.web...
  [javadoc] Constructing Javadoc information...
  [javadoc] Standard Doclet version 1.4.1

  [javadoc] Building tree for all the packages and classes...
  [javadoc] Building index for all the packages and classes...
  [javadoc] Building index for all classes...

warfile:
    [mkdir] Created dir: /Applications/springframework/samples/petclinic/dist
      [war] Building war: /Applications/springframework/samples/petclinic/dist/petclinic.war

BUILD SUCCESSFUL
Total time: 5 seconds

Before I moved the petclinic.war file from the dist directory to the Tomcat's webapps directory, I did a couple of things. First, started up the HSQLDB database that is used in the demo:

cd /Applications/springframework/samples/petclinic/db
java -classpath ../../lib/hsqldb.jar org.hsqldb.Server -database petclinic
Opening database: petclinic
HSQLDB server 1.7.1 is running
Use SHUTDOWN to close normally. Use [Ctrl]+[C] to abort abruptly
Tue Jul 01 13:22:16 CDT 2003 Listening for connections ...

Then, because I wanted to watch how Tomcat reacted to me putting the petclinic.war file into its webapps directory, I said

tail -f /Applications/tomcat/logs/localhost_log.2003-07-01.txt

so the log would be displayed in a Terminal window. Then I moved the petclinic.war file from the /Applications/springframework/samples/petclinic/dist directory into the /Applications/tomcat/webapps directory.

I went to http://127.0.0.1:8080/ and clicked on Tomcat Manager. It now listed the petclinic application. I clicked on Start to start it, then clicked on the path to go to it:

I had a lot of problems figuring this out, which is why I wrote this Howto. For some reason the war file ant generated for me the first time did not include the proper jar files in the WEB-INF/lib directory and that threw me off. Also, the HSQLDB database was not starting up. Thanks for Thomas Risberg for helping out.