Spring is under constant development with many new features being added almost daily. If you want to get a grip on new features before they make their way into a release, then obtaining the latest source code from CVS is the best way of going about it.

To check out the latest version of the Spring code, install CVS, which you can download from www.cvshome.org, and run the following command:

cvs -d:pserver:[email protected]:

/cvsroot/springframework login

When prompted for your password, simply press Enter to send a blank password. Next, enter the following command to check out the HEAD of the CVS repository, which contains the latest changes that have been committed:

cvs -z3 -d:pserver:[email protected]:

/cvsroot/springframework co -P spring

This command gives you the absolute latest version of the code, including two separate source trees: one contains the main source for Spring including any new features considered stable enough to be in the main tree; and the other, the sandbox, contains code still classified as work in progress. New code in the main tree is likely to make it into the next release, but code in the sandbox might not. Be aware that any new code is subject to change without notice; for this reason, avoid basing any of your new applications around unreleased code.

Older versions of Spring are stored in CVS tagged by their version number, so you can download any version of Spring directly from CVS. If you are unsure of the tags to use, you can find them by browsing the CVS repository online at http://springframework.cvs.sourceforge.net/springframework/.

Let's take a look at how we can compile the framework from the source code. Even though it is possible to compile the HEAD version from CVS, we recommend that you compile one of the final releases. In the following example, we will take the latest version of Spring available at the time of this writing, version 2.5.2. The CVS tag for the source is release-2–5–1; you will need to run the commands in Listing 2-1 to check out the tag.

cvs -d:pserver:[email protected]:

/cvsroot/springframework login
cvs -z3 -d:pserver:[email protected]:

/cvsroot/springframework co -r release-2-5-2 -P spring

Assuming that you have Apache Ant installed, that you have set the $ANT_HOME environment variable, and that the $PATH includes $ANT_HOME/bin, you can run ant alljars. This will build all source code and produce the Spring JAR files. The JAR files will be created in the dist directory, whose full structure is shown in Listing 2-2.

janm@janm-ff:~/spring/dist$ find -iname *.jar | sort -r
./weaving/spring-tomcat-weaver.jar
./weaving/spring-aspects.jar
./weaving/spring-agent.jar
./weaving-sources/spring-tomcat-weaver-sources.jar
./weaving-sources/spring-aspects-sources.jar
./weaving-sources/spring-agent-sources.jar
./spring-sources.jar
./spring.jar
./modules/spring-webmvc-struts.jar
./modules/spring-webmvc-portlet.jar
./modules/spring-webmvc.jar
./modules/spring-web.jar
./modules/spring-tx.jar
./modules/spring-test.jar
./modules/spring-orm.jar

./modules/spring-jms.jar
./modules/spring-jdbc.jar
./modules/spring-core.jar
./modules/spring-context-support.jar
./modules/spring-context.jar
./modules/spring-beans.jar
./modules/spring-aop.jar
./module-sources/spring-web-sources.jar
./module-sources/spring-webmvc-struts-sources.jar
./module-sources/spring-webmvc-sources.jar
./module-sources/spring-webmvc-portlet-sources.jar
./module-sources/spring-tx-sources.jar
./module-sources/spring-test-sources.jar
./module-sources/spring-orm-sources.jar
./module-sources/spring-jms-sources.jar
./module-sources/spring-jdbc-sources.jar
./module-sources/spring-core-sources.jar
./module-sources/spring-context-support-sources.jar
./module-sources/spring-context-sources.jar
./module-sources/spring-beans-sources.jar
./module-sources/spring-aop-sources.jar

These JAR files are the same ones you can get in the Spring binary distribution; in the next section, we will take a more detailed look at the packages.

With every distribution, you get the full source code for the test suite, along with the Ant script you need to run the tests and produce the test report. If you think your distribution has a bug, first run the test suite to see if the bug is highlighted in one of the tests. Although many open source projects claim that most bugs are in user code and not in their code, Spring can back this up with a test suite that consists of thousands of tests. Don't just take our word for it; you can run all Spring tests by running ant tests at the command line.

We do not recommend that you build Spring from source code and use the compiled code in your day-to-day development. It is much easier and much more convenient to use automated tools such as Maven 2 to determine which version of Spring, and other libraries, your application needs to compile, test, and run.

When you unzip the full Spring distribution or compile the source distribution, the dist subdirectory contains the full Spring distribution. However, there are many different JARs and, even more confusingly, spring.jar. The reason for this split is that some applications may not require the entire Spring Framework. The decision whether to use various smaller JARs or the entire spring.jar depends on the type of application you are writing and on its environment.

Most applications work absolutely fine with the entire spring.jar on the classpath. However, if you deploy your application in an application server that already contains other versions of the Spring Framework libraries, you may come across versioning conflicts. Another situation where you may not want to include the entire spring.jar in your application is if you wish to use only parts of the Spring's code. Table 2-1 summarizes all the Spring JARs that are included in the default distribution.

As we said before, each of these JARs contains fragments of the entire Spring distribution. However, spring.jar is still not the entire distribution of Spring. The spring.jar library does not include the code in the spring-mvc-*.jar files.

If we leave the dist directory and go to the lib directory, you will notice that it contains a large number of libraries. These dependencies are necessary to build and test the entire Spring Framework distribution, but not all of the dependencies will be needed in your applications. Table 2-2 lists the Spring 2.5 dependencies, including their short descriptions.

We found that the best way to create applications is to start with the minimal set of dependencies and only add another JAR if necessary. The main reason for this is neither speed nor size but the possibility of conflict when two dependent libraries rely on different versions of the same library. In this case, most developers take the latest (or later) version and try to get the application to compile. If that works and the tests verify that the application is working correctly, they assume that the conflict is resolved. This approach usually works, and until there is more widespread support for OSGi modules, we have no other choice. Welcome to JAR hell!

An area where many open source, and indeed commercial, products fail is in providing enough well documented sample code to make it easy for people to get started. Thankfully, Spring comes with a complete set of nifty sample applications that demonstrate a wide selection of the features in Spring. A point to note is that the sample applications are treated as first-class citizens of the framework by the development team, and they are constantly being improved and worked on by the team. For this reason, you generally find that, after you get what you can from the test suite, the samples are a great place to get started when you are looking at new features.

The PetClinic Application

PetClinic is an interesting sample application that was built to showcase Spring's data access support. In it, you find a web-based application for querying and updating the database of a fictional veterinary office. The interesting thing about this application is that it comes with a selection of interchangeable data access implementations that highlight how easy it is to decouple your application from the data access logic when you are using Spring.

The Hibernate data access implementation really shows off Spring's Hibernate support by implementing each of the eight data access methods with a single line. The JDBC implementation is equally interesting. First, much of the JDBC logic is contained in an abstract base class. This class provides hook methods for subclasses when you need to use provider-specific SQL features—in the PetClinic case, this happens with the automatic generation of primary keys. Second, when you are looking at the base class, it is interesting to see how much of the repetitive error-handling code that is prevalent when you are using JDBC is removed. Third, it is very interesting to see how data access is handled in a much more object-oriented way.

This project also contains a very solid example of how to build a web application using Spring's MVC support, so if you are planning to use Spring MVC for one of your own applications, make sure you take a look at this sample first.

We cover JDBC support in Chapter 9, Hibernate in Chapter 11, and Spring MVC in Chapter 17.

The PetPortal Application

This application offers sample implementation of the Portlet MVC support in Spring using the favorite pet shop scenario. It is a simplified jPetStore application; it demonstrates wizard-style controllers and validators, file upload handling, and redirection to external web sites.

The jPetStore Application

The jPetStore application is based on the jPetStore sample created by Clinton Begin for iBATIS. As far as sample applications go, this one is huge. It contains a full DAO layer, created using Spring and iBATIS, with implementations for Oracle, Microsoft SQL Server, MySQL, and PostgreSQL. The business tier is fully Spring managed and, coupled with the DAO layer, it presents a good example of Spring-managed transactions.

Also included with this application is a solid example of how to use both Spring MVC and Struts. This application also highlights how to use Spring remoting using JAX-RPC.

Spring MVC is covered in Chapters 17, iBATIS in Chapter 10, and Spring remoting in Chapter 15.

The Tiles Example Application

Tiles is one of our favorite open source tools, because it reduces a lot of the drudge work when you are building user interfaces for the Web, and it really helps separate individual UI elements into reusable fragments. Because of this, the Tiles support in Spring is especially welcome, and this sample application makes getting started with Tiles in your own sample application easy.

We cover Tiles in detail in Chapter 17.

The ImageDB Application

This is one of our favorite sample applications, because it shows off loads of useful Spring features. Specifically, you see how to load and store large binary objects (LOBs) in a database, how to handle file uploads, and how to schedule jobs using the Quartz job scheduler. As if that weren't enough, you also see how to use Velocity as the view technology in the web tier.

We cover LOBs in Chapters 9 and 11, file uploads in Chapter 17, job scheduling in Chapter 12, and Velocity support in Chapter 17.

The JasperRepots Application

Reports are one of the most dreaded programming tasks; this application shows how to use the JasperReports framework to ease the development of PDF and Excel reports without a single line of Java web code. We discuss the reporting support in Chapter 17.

JCA-10 Application

The aim of the sample is to show how to use the support of JCA CCI 1.0 in Spring. It uses the sample JCA connector of the Java EE SDK version 1.3 modified to be used with Hypersonic and to execute SQL requests directly on the CCI interaction specification. The connector of the sample only supports local transactions and works in a stand-alone mode.

To use it in a managed mode, you must package the JAR in spring-cciblackbox-tx.rar and deploy it on your JCA 1.0-compliant application server (for example, JBoss 4).

The Countries Application

This is an intriguing example that demonstrates some of the more advanced features of Spring MVC. It looks at using HandlerInterceptors to provide common preprocessing for your controllers as well as utilizing Excel and PDF output for the view technology. This example is quite small and is certainly worth a look if you are planning to use Excel or PDF within your application. We cover HandlerInterceptors as well as Excel and PDF integration in Chapter 16.

Now that you have the full Spring distribution, it is time to look at how you set it up in your favorite IDE. While you can use command-line tools (such as ant and maven) to build your applications, working in an IDE is much more comfortable. Also, having the Spring libraries set up is useful, so you can step into their code. We will use IntelliJ IDEA, though other IDEs are just as easy to set up.

Regardless of your choice of IDE, let's first examine the directory structure of the applications we will show in this book. Figure 2-1 shows the directory structure of the sample application for this chapter.

Figure 2.1. Directory structure of the sample application

The directory structure shows that we have one src directory that contains code for the main code and test code. Each of the test and main source directories further has the java and resources subdirectories. All Java code goes into the java directory; all other files that are not Java source code, but make up part of the application, go to the resources directory. Next, we have the lib directory at the same level as the entire project. We do not just leave all JAR files in the lib directory; instead, we create subdirectories with some descriptive names. For the application in this chapter, we will only need the lib/org/springframework/spring.jar library. Figure 2-2 shows how we have set up the module in IntelliJ IDEA—you can clearly see the source and test source directories.

Figure 2.2. IntelliJ IDEA module setup

This would be enough to start writing plain Java code, but we know that we are going to write some Spring code! To prepare for that, we need to add the libraries we are going to need: spring.jar and commons-logging-1.1.jar. Figure 2-3 shows these libraries set up in IntelliJ IDEA.

Figure 2.3. Library setup in IntelliJ IDEA

In Figure 2-3, you can see that we have added the spring.jar library and its dependency, commons-logging-1.1. We have also attached the spring-sources.jar, which contains the source code compiled into spring.jar. Finally, Figure 2-4 shows that we have added the two libraries as module dependencies.

Figure 2.4. Module dependencies

Once you have all this set up, you are ready to follow the source code we are going to show in this chapter. Alternatively, you can open the sample application project, which includes code for all chapters.

The code you have seen until now does not use the DI pattern. It uses dependency lookup. We will explore the dependency injection pattern in far more detail in the next chapter, but for now, consider that the code in FirstSpringHelloWorld had to know the names of the MessageSource and MessageDestination beans. It had to look them up and then use them. This clouds the implementation, because in addition to the problem we are trying to solve, we need to know details about the setup of the application. It would be much better if the MessageSource and MessageDestination interfaces somehow got automatically set. To get you started, we will show you how to create a MessageService, which uses MessageSource and MessageDestination beans, but we will use Spring to inject the MessageSource and MessageDestination beans into the MessageService bean. Listing 2-9 shows the implementation of MessageService.

public interface MessageService {

    void execute();

}

public class DefaultMessageService implements MessageService {
    private MessageSource source;
    private MessageDestination destination;

    public void execute() {
        this.destination.write(this.source.getMessage());
    }

    public void setSource(MessageSource source) {
        this.source = source;
    }

    public void setDestination(MessageDestination destination) {
        this.destination = destination;
    }
}

We intend to use the implementation of the MessageService, the DefaultMessageService, in the main method in the DISpringHelloWorld example. If you look at the code in Listing 2-10, you will see that we only get the service bean, but we do not control the creation and life cycle of the service bean—we leave that to Spring.

public class DISpringHelloWorld {

    public static void main(String[] args) {
        DefaultListableBeanFactory bf = new DefaultListableBeanFactory();
        BeanDefinitionReader reader = new PropertiesBeanDefinitionReader(bf);
        reader.loadBeanDefinitions(
          new ClassPathResource("/META-INF/spring/helloworld2-context.properties"));

        MessageService service = (MessageService) bf.getBean("service");
        service.execute();
    }

}

The last piece of puzzle is the helloworld2-context.properties file. Somehow, this file must contain enough information to tell Spring that to create an instance of bean named service, it must first create instances of the source and destination beans and then inject them (e.g., invoke the setSource and setDestination methods) on the service bean. Listing 2-11 shows just how easy it is to do that.

source.(class)=com.apress.prospring2.ch02.decoupled.source.SimpleMessageSource
destination.(class)=com.apress.prospring2.ch02.decoupled.destination.

StdoutMessageDestination
service.(class)=com.apress.prospring2.ch02.spring.DefaultMessageService    # 1
service.source(ref)=source    # 2
service.destination(ref)=destination    # 3

Line number one defines a bean named service as an instance of DefaultMessageService. The dependency injection instructions are on the lines numbered two and three. When we then call getBean("service") in the main method, Spring will use this information to create the three beans and return the fully constructed instance of the DefaultMessageService.

There is much more to dependency injection in Spring, and we give far more detail in the following chapters, but this is a good starting point for further experiments. The most difficult part to grasp for Spring newbies is that the objects seem to live in thin air; it is usually difficult to give up control over construction of objects and let the framework handle it.

If you design your application in a similar way to the design we have taken in the last section of this chapter, the impact of using the Spring Framework will be absolutely minimal. Spring heavily promotes coding to interfaces—your code should be split into interfaces and their implementations. The interfaces form the beans that other beans can use, as you have seen in MessageSource, MessageDestination, and more crucially, MessageService. The implementations then take full advantage of the dependency injection, but at no point do the various implementations of the interfaces need to be aware of each other. This gives the ultimate flexibility and testability of the applications you will create.

Even more importantly, the code in the interfaces and implementations is plain Java code; the implementations are not aware of the fact that they are running in a dependency injection context.