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

/aspectj

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.

/dist

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.

/docs

Spring’s API and reference documentation.

/lib

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.

/mock

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

/samples

Several example Spring applications.

/src

Source code for most of the Spring Framework.

/test

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

/tiger

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

Directory

Purpose

spring.jar

dist/

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

spring-aspects.jar

dist/

Spring’s AspectJ-specific classes.

spring-mock.jar

dist/

Spring’s mock objects and testing classes.

spring-aop.jar

dist/modules/

The Spring AOP module.

spring-beans.jar

dist/modules/

The Spring bean factory module.

spring-context.jar

dist/modules/

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

spring-core.jar

dist/modules/

Classes that are core to the Spring Framework.

spring-dao.jar

dist/modules/

The basis for Spring’s DAO support.

spring-hibernate2.jar

dist/modules/

Spring’s Hibernate 2 support.

spring-hibernate3.jar

dist/modules/

Spring’s Hibernate 3 support.

spring-ibatis.jar

dist/modules/

Spring’s iBatis support.

spring-jca.jar

dist/modules/

Spring’s JCA support.

spring-jdbc.jar

dist/modules/

Spring’s JDBC module.

spring-jdo.jar

dist/modules/

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

spring-jms.jar

dist/modules/

Spring’s support for JMS.

spring-jmx.jar

dist/modules/

Spring’s JMX support.

spring-jpa.jar

dist/modules/

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

spring-portlet.jar

dist/modules/

Spring’s portlet MVC framework.

spring-remoting.jar

dist/modules/

Spring’s remoting module.

spring-struts.jar

dist/modules/

Spring’s support for Struts and Tiles.

spring-support.jar

dist/modules/

Support and utility classes.

spring-toplink.jar

dist/modules/

Spring’s support for Oracle TopLink.

spring-web.jar

dist/modules/

Spring’s web application context and utilities.

spring-webmvc.jar

dist/modules/

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:

set CLASSPATH=%CLASSPATH%;{SPRING_HOME}/dist/spring.jar
set CLASSPATH=%CLASSPATH%;{SPRING_HOME}/lib/
     jakarta-commons/commons-logging.jar

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

spring

Almost all of the Spring Framework

spring-aop

The Spring AOP framework

spring-aspects

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

spring-beans

The Spring bean factory and related classes

spring-context

The Spring application context and related classes

spring-core

The core Spring Framework

spring-dao

Spring’s DAO abstraction framework

spring-hibernate2

Spring’s support for Hibernate 2

spring-hibernate3

Spring’s support for Hibernate 3

spring-ibatis

Spring’s support for iBATIS

spring-jca

Spring’s support for the Java Connector API

spring-jdbc

Spring’s JDBC abstraction framework

spring-jdo

Spring’s support for Java Data Objects

spring-jms

Spring’s support for the Java Messaging API

spring-jmx

Spring’s support for Java management extensions

spring-jpa

Spring’s support for the Java Persistence API

spring-mock

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

spring-ojb

Spring’s support for Apache’s Object Relational Bridge

spring-portlet

Spring’s Portlet MVC framework

spring-remoting

Spring’s remoting support

spring-struts

Spring-Struts integration

spring-support

Support and utility classes

spring-toplink

Spring’s support for Oracle TopLink

spring-web

Spring’s web container and related utility classes

spring-webmvc

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:

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-aop</artifactId>
  <version>2.0.3</version>
</dependency>

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:

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring</artifactId>
  <version>2.0.3</version>
</dependency>

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:

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-hibernate3</artifactId>
  <version>2.0.3</version>
</dependency>

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:

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-mock</artifactId>
  <version>2.0.3</version>
  <scope>test</scope>
</dependency>

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:

<dependency>
  <groupId>javax.servlet</groupId>
  <artifactId>servlet-api</artifactId>
  <version>2.4</version>
  <scope>provided</scope>
</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:

<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>1.2.13</version>
  <scope>compile</scope>
</dependency>

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=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d %p %c - %m%n
log4j.rootLogger=INFO, stdout
log4j.logger.org.springframework=DEBUG