Realsolve - Getting Started With Spring

Getting Started With The Spring Framework Using Eclipse

A Step-by-Step Guide

By Phil Zoio, 23 December 2004

Author's Note (October 2008). This article was written almost four years ago, and may still be useful for a simple Spring setup. For an ultra-productive, modular, Spring-based development environment that works out the box with almost no setup, check out Impala, a project I've been working on. There's an article on this site, some samples to play with, and instructions to kickstart your own project.

If you're a Java enterprise software developer and haven't started using the Spring Framework, you're probably pretty keen to give it a try. This article explains how to rapidly create an effective development environment for building Spring-based applications, using the Eclipse IDE.

One of the nice things about Spring is that it is so easy to get started with. It provides a fairly comprehensive set of samples. You also have the option of downloading the framework together with all its library dependencies as a single zip file, which is particularly useful if you want to get it working quickly. It also includes all the build files necessary to build the samples. Deploying them is simply a matter of copying the built Web Application Archive (WAR) files into your Servlet container's web application deployment directory.

Once you've seen a few of the examples in action, the next thing you're likely to want to do is to create your own development environment. This article go through a step-by-step approach to getting a Spring development environment working with the Eclipse IDE.

This article has been written for the following environment:

JDK 1.4.2 or later
Spring 1.1.2
Eclipse 3.1

The Steps

1. Download the Spring source

You can get the latest release of Spring from SourceForge by following the links from the web site (www.springframework.org). There doesn't appear to be a binary distribution of Spring. That doesn't matter, because it is so easy to build from source. Just download the file spring-framework-1.1.x-with-dependencies.zip, then unzip it to where you want it on your development machine

2. Build the Binary from Source

Here, all you need to do is set your JAVA_HOME environment variable, then navigate to your Spring Framework install folder on the command line, then run

build alljars

This launches an ANT task to build the framework. All of the Spring jar files will be created in the spring installation dist directory.

3. Play with the Samples

The next thing to do is to try out some of the samples, which you can find in source form in the samples directory. Once again, building these from source is really easy. Go to the relevant sample application (say countries), then run

build all

This creates a WAR file which you can simply put in your Servlet container's webapp folder. Then start your server, and type in your brower the URL to your web application, which may be something like this:

http://localhost:8080/countries

If you've spent a bit of time playing with the samples or want to get hands on from the start, you can skip this step.

4. Create a new Eclipse project

The rest of the tutorial assumes you are using Eclipse as your IDE. Eclipse is an excellent Java IDE which is free and has great external support by providers of plugins. Spring has an Eclipse-based development tool as a sub-project, called Spring IDE. If you're using another IDE, this tutorial obviously won't be as useful, you could easily mirror these steps using another tool.

From within Eclipse, create a new Java project, calling it spring-test (You can call it anything you like, but for the sake of this tutorial, this is what we call it). At this stage the project will be empty.

5. Copy the Spring web-app minimal sample

Spring comes with a sample minimal web application, called webapp-minimal, and found in the samples directory of the Spring installation. This is the equivalent of "Hello World" for Spring. It contains all the files necessary to build a minimal but fully functionaly web application.

Copy the contents of this folder into the spring-test project folder. Then refresh the workspace so that the copied files are reflected within Eclipse.

6. Add a new souce folder

The minimal web application contains one folder with Java source files in it: spring-test/webapp-minimal/src

Add this as a source folder to your Java project as follows:
Right click on spring-test project in 'Package Explorer' view
Select Properties to open the Properties dialog
Select the 'Java Build Path' properties page
Open the 'Source' tab
Click on the 'Add Folder ...', then select spring-test/webapp-minimal/src

This brings you to a screen which looks like this:

Eclipse project configuration

Select 'OK'

7. Add project dependencies

At this point, Eclipse will try to compile your source, and will probably notify you of all sorts of errors during compilation. This is because you still need to add the dependencies. The only dependencies needed for the webapp-minimal project are:

spring.jar
commons-logging.jar
servlet.jar

Add these to the folder webapp-minimal/lib as follows:

Navigate to the 'Java Build Path' properties page as described in the previous step.
Then Open the 'Libraries' tab, and click on 'Add Jars ...'. Because the dependent jar files are in the project workspace, you can navigate to them in the webapp-minimal/lib.
Select all of these and add them to the project, as shown below.
Then Select 'OK'. At this point, Eclipse will rebuild your project, and with a little luck remove all the errors.

8. Create an ANT build configuration

As we know, Spring has already created a build file for the web application. Now we simply need to add an Eclipse ANT build configuration. To do this we right click on webapp-minimal/build.xml

The select

Run As -> External Tools ...

This brings up the 'External Tools' dialog, which we can use to create an ANT runtime configuration.

Using the UI should be fairly self-explanatory. The only thing you will need to do is select a target for your build file, which you can do by navigating to the 'Targets' tab and selecting 'warfile'. This is the build target which, when launched, will create your WAR.

Once you've done this, you will probably want to add ANT build configurations for the 'clean' target, so that you can clean your development environment through the IDE.

As mentioned, the WAR will go into the dist directory, so you still need to copy it manually into the webapp directory of your servlet container at this point. This is obviously a drag so you'll want to fix this once you've got going.

9. Optimize your build

Iterative development on a large project with many folders is too slow if you need to build a WAR every time you make a change. This applies particularly when editing HTML or JSP pages. Servlet containers such as Tomcat and Resin allow you to deploy directly in 'expanded' mode. Instead of copying the WAR file into the webapp directory, you copy webapp-minimal directory into this directory. ANT will only copy modified files. Also, Tomcat does not redeploy the whole web application if you are only modifying JSPs - it simply reloads the generated Servlet class.

To create an optimised build, you need to make two changes.

In webapp-minmal/build.properties, add a remote.dir property to reflect the location of your Servlet container's web application folder

remote.dir=F:/servers/tomcat-4.1.31/webapps

Add another couple of targets to your ANT build XML, as shown in the snippet below


<target name="copy-remote" depends="build" description="Copy expanded web application to remote webapp folder location">
  <!-- create directory to copy file to remotely -->
  <mkdir dir="${remote.dir}/${name}" />

  <!-- copy war folder contents to ${remote.dir}/${name} -->
  <copy todir="${remote.dir}/${name}">
    <fileset dir="${war.dir}" />
  </copy>

  <!-- copy lib folder to remote directory ${remote.dir}/lib -->
  <copy todir="${remote.dir}/${name}/WEB-INF/lib">
    <fileset dir="${lib.dir}">
      <exclude name="servlet.jar" />
    </fileset>
  </copy>
  <!-- copy classes to ${remote.dir}/lib -->
  <copy todir="${remote.dir}/${name}/WEB-INF/classes">
    <fileset dir="${build.dir}" />
  </copy>
</target>

<target name="clean-remote" depends="clean" description="Remove expanded web application and clean">
  <!-- delete remote webapp directory -->
  <delete dir="${remote.dir}/${name}" />
</target>

The first target simply uses the ANT copy task to copy the web application, the dependent libraries and the compiled classes to the target location. The second target simply cleans the Servlet container's web application directory, in case you need to rebuild from scratch.

Finally, you will want to create an ANT build configuration for these targets, so that you can launch these from the IDE. The final product looks like this:

Final project configuration

Summary

Follow these steps as outlined above and you will be well on your way to having a slick application development environment for Spring-based applications in very little time indeed. It hardly needs to be said that the quicker you can get started building applications yourself in an IDE, with its powerful debugging and source code navigation features, the quicker you will become productive using the Spring Framework.

This is a working document. If there are any errors, or if you disagree with anything which I have said, or have any suggestions for improvements please email me at philzoio@realsolve.co.uk.