A. Setting up Spring – Spring in Action, Second Edition

Appendix A. Setting up Spring

The Spring Framework and container is packaged in several JAR files. Spring is a library of classes that will be packaged with and used by your Spring-enabled applications. Installing Spring involves adding one or more JAR files to your application’s classpath. It does not have an executable runtime. Therefore, Spring is more akin to a library like Jakarta Commons than an application server like JBoss.

How you make Spring available to your application’s classpath will vary depending on how you build and run your application. You may choose to add the Spring JAR files to your system’s classpath or to a project classpath in your favorite IDE. If you’re building your application using Ant or Maven, be certain to include Spring in your build’s dependencies so that it will be included in the project’s target deployment.

Even though you happen to be holding one of the best books ever published about Spring (I’m not biased, though), there’s plenty of additional materials in Spring’s full distribution, including Spring’s API documentation, examples, and the full source code for the Spring Framework. Therefore, the first thing you’ll want to do is to download the full Spring distribution. Let’s see where you can find Spring and what you’ll get when you download it.

Downloading Spring

You can download the Spring distribution from Spring’s website: http://www.springframework.org. Choose the downloads link from the left-hand menu and look for the Spring 2.0 download. As I’m writing this, I’m building the examples against version 2.0.6.

When downloading Spring, you have two choices: you can download a Spring distribution that comes with its own dependencies or you can download a distribution that contains only the Spring JAR files. Even though it’s a much larger download, I favor the one that comes with dependencies so that I won’t have to hunt down the other JAR files that my application needs.

Exploring the Spring distribution

Once you’ve downloaded the distribution, unzip it to a directory on your local machine. The Spring distribution is organized within the directory structure described in table A.1.

Table A.1. Spring’s full distribution contains a wealth of materials, including API documentation, source code, and examples.

Distribution path

What it contains


Source files for Spring-specific aspects implemented in AspectJ. If you’re curious about how the Spring Framework makes use of AspectJ, you’ll want to look in here.


The Spring distribution JAR files. Here you’ll find several JAR files, each of which represents a part of the Spring Framework, as described in table A.2 in the next section.


Spring’s API and reference documentation.


Open source JAR files that Spring depends on, including Log4j, AspectJ, Jakarta Commons, Hibernate, and others. Fear not: Spring doesn’t depend on all of these JAR files. Many of them only come into play when you exercise a specific set of Spring functionality.


The source code for Spring’s mock object and unit-testing module.


Several example Spring applications.


Source code for most of the Spring Framework.


Source code for the unit tests that are used to test Spring itself.


Source code for the portion of Spring that is specific to Java 5. This code is kept separate from the core of Spring to ensure that the rest of the framework is compatible with older versions of Java.

Several of these directories contain the Spring source code. The aspectj/, mock/, src/, and tiger/ directories contain the source code that makes up the Spring Framework itself. Meanwhile, the test/ directory contains the unit tests used to test Spring. Although it’s not essential to using Spring, you may want to venture around in these directories to see how Spring does its stuff. The Spring developers are extremely talented coders and you’ll probably learn a little something by reviewing their code.

The docs/ directory contains two important pieces of documentation. The reference document is an overview of the entire Spring Framework and is a good complement to this book. Also, the JavaDocs for the entire Spring Framework can be found under docs/—you’ll probably want to add this as a bookmark in your web browser, because you’ll refer to it often.

The samples/ directory contains a handful of sample Spring applications. Of particular note are the petclinic and jpetstore examples. Both of these applications highlight many important elements of the Spring framework.

Building your classpath

The most important directory in the Spring distribution is probably the dist/ directory. That’s because this is the directory containing the JAR files that you’ll use to build Spring-based applications. Using Spring in your application involves choosing one or more JAR files from this directory and making them available in your application’s classpath. The JAR files and their purposes are described in table A.2.

Table A.2. The JAR files that make up the Spring Framework. The framework is broken into several modules, enabling you to pick and choose the parts of Spring that you need for your application.

JAR file





Contains most of the modules of the Spring Framework in one convenient JAR file.



Spring’s AspectJ-specific classes.



Spring’s mock objects and testing classes.



The Spring AOP module.



The Spring bean factory module.



The Spring application context module. Includes JNDI, validation, scripting, Velocity, and FreeMarker libraries.



Classes that are core to the Spring Framework.



The basis for Spring’s DAO support.



Spring’s Hibernate 2 support.



Spring’s Hibernate 3 support.



Spring’s iBatis support.



Spring’s JCA support.



Spring’s JDBC module.



Spring’s support for Java Data Objects (JDO).



Spring’s support for JMS.



Spring’s JMX support.



Spring’s support for the Java Persistence API (JPA).



Spring’s portlet MVC framework.



Spring’s remoting module.



Spring’s support for Struts and Tiles.



Support and utility classes.



Spring’s support for Oracle TopLink.



Spring’s web application context and utilities.



Spring MVC.

Although the list of 24 JAR files may seem a bit daunting, sorting them out isn’t all that difficult. The JAR files in the dist/modules/ directory allow you to choose which parts of Spring are needed for your application. To make things simple, however, you may want to take the lazy way out and simply add spring.jar (from the dist/ directory) to your application’s classpath. The spring.jar file is a convenient, single-JAR equivalent to all of the JARs in the dist/modules/ directory.

You should know that not all Spring-related JAR files are available in the main Spring distribution. Acegi Security and Spring-WS, for example, are subprojects of Spring and have their own distributions available from their own websites. When it comes time to add these modules to your classpath, I’ll be sure to tell you where to find them.

If dist/ is the most important directory then lib/ comes in a close second. You will likely need to add other JAR files to your classpath to enable certain Spring features. For example, if you intend to use Spring’s support for AspectJ in your application, you’ll need to add aspectjrt.jar and aspectjweaver.jar to the classpath. Likewise, Spring’s Hibernate modules depend on an appropriate version of Hibernate being available in the classpath. If you downloaded the “with dependencies” distribution of Spring, you’ll be able to find most dependencies you need in the lib/ directory.

Although many of the JAR files under the lib/ directory are optional, one is required. Spring relies on Jakarta Commons Logging to log informational and error messages. Therefore, commons-logging.jar (from lib/jakarta-commons) must always be in the classpath of any Spring-enabled application.

Once you’ve decided which JAR files your application needs, the next step is to add them to your classpath. The naive way of handling this would be to add them to your CLASSPATH system variable:


This may work for quick-and-dirty experimentation. But you’re probably going to use Spring to develop full-blown applications more often than one-off trials. You’re likely going to let a build system like Maven or Ant construct your application distribution. In the following sections, we’ll show you how to add Spring to your Maven and Ant builds.

Adding Spring as a Maven 2 dependency

If you’re using Maven 2 to build and package your Spring-based application, you can let Maven download the Spring JAR files for you. With Maven 2, adding Spring to your build is a simple matter of adding dependency entries to your project’s pom.xml file.

Spring and its modules are available in the Maven repository under the group ID org.springframework. Within this group are the modules listed in table A.3.

Table A.3. The Spring modules available in the Maven 2 repository. To include these in your application’s build, you’ll need to add a <dependency> entry to your pom.xml file.

Maven artifact ID

What it provides


Almost all of the Spring Framework


The Spring AOP framework


AspectJ aspect library, including the Spring-configured and AspectJ transactional aspects


The Spring bean factory and related classes


The Spring application context and related classes


The core Spring Framework


Spring’s DAO abstraction framework


Spring’s support for Hibernate 2


Spring’s support for Hibernate 3


Spring’s support for iBATIS


Spring’s support for the Java Connector API


Spring’s JDBC abstraction framework


Spring’s support for Java Data Objects


Spring’s support for the Java Messaging API


Spring’s support for Java management extensions


Spring’s support for the Java Persistence API


Spring’s unit-testing and mock-object extensions.


Spring’s support for Apache’s Object Relational Bridge


Spring’s Portlet MVC framework


Spring’s remoting support


Spring-Struts integration


Support and utility classes


Spring’s support for Oracle TopLink


Spring’s web container and related utility classes


Spring’s web MVC framework

You may choose to add each module as a dependency as it’s needed. For example, if your application depends only on the Spring AOP module, you might add the following <dependency> to your pom.xml file:


This dependency declaration will make Spring AOP available for building your application. In addition, the Spring Beans module will be made available thanks to Maven 2’s support for transitive dependency resolution.

Although your application may start small and have only a small dependency on Spring, most applications grow to depend on the bulk of the Spring Framework. Therefore, it is often easier to declare a dependency on the entirety of Spring:


This dependency will make the bulk of the Spring Framework available to your application. Even if you’re not using it all right away, there’s little harm (and plenty of convenience) in using this dependency.

If your application will be using a third-party ORM solution or you will be building a portlet MVC application, you may need to add additional dependencies to pom.xml. For example, if your application is using Hibernate 3 for persistence, you’ll want to add the Spring Hibernate 3 module as follows:


Likewise, you may want to take advantage of Spring’s mock objects and testing support classes. If that’s the case, add the following dependency to pom.xml:


Notice that the <scope> of this dependency is test. This ensures that the Spring Mock module will only be available during testing and not packaged for distribution with your application.

If your application is using Spring MVC, you’ll need to add Servlet API JAR file as a dependency:


In this case, the <scope> has been set to provided. This tells Maven to make the Servlet API available at compile time, but not to include it in a WAR packaging. The Servlet API is usually made available by the application server and should not be included in an application deployment.

Maven 2 has gained a lot of attention in the last year or so. But if you haven’t made the switch to Maven 2, odds are that you’re an Ant fan. Although I favor Maven 2 for my builds, I won’t leave the Ant fanatics hanging. Let’s see how to build a Spring-based application using Ant.

Spring and Ant

Although I prefer to use Maven 2 for my builds, many developers will want to use Apache Ant. If you’re using Ant to build your Spring project, you’ll need to download the Spring Framework for yourself (as described in section A.1) and add the Spring JAR files and their dependencies to the appropriate paths in your project’s build.xml file.

I recommend declaring an Ant <path> element that will contain all of your application’s dependencies, including the Spring JAR files. Listing A.1 shows a small section of an Ant build file that manages Spring dependencies in this way.

Example A.1. Building a Spring application with Ant

Regardless of whether you choose Maven 2 or Ant (or some other build mechanism), you’ll probably want to configure Log4j to properly handle Spring logging. Let’s see how to set up Spring with Log4j.

Spring and Log4j

With the build file now in place, there is one final thing you will want to do. When you first start using Spring, one feature you’ll almost certainly find useful is logging. First, be sure that the Log4j JAR file is in the application’s classpath. If you’re using Ant to do your build, the build.xml file in listing A.1 already includes Log4j (through the ${spring.lib.dir} path). If you’re using Maven 2, simply add the following <dependency> to your pom.xml file:


With Log4j in the application’s classpath, the next thing to do is include a simple Log4j configuration file. Assuming the project structure defined in the build.xml file in listing A.1, you will need to create a file called log4j.properties in /src/ webapp/WEB-INF/classes. The following snippet of log4j.properties configures Log4j to log all of Spring’s logging messages to the console:

log4j.appender.stdout.layout.ConversionPattern=%d %p %c - %m%n
log4j.rootLogger=INFO, stdout