You need Apache Maven, version 2.0.9 or greater. Maven isn't strictly necessary if you've already got an existing Spring Roo project, but it's definitely convenient and is required to do things like use Roo's commands for dependency management, builds, project bootstrapping, and so on.

Eclipse is an ideal environment, because it has support for the AspectJ Development Tools (AJDT). This support lets you code in Eclipse with aspects as a first class member of the language; aspects are transparently woven in and everything compiles. All mechanisms—refactoring, class inspection and IDE pop ups—work as you'd expect. Unfortunately, this support is limited to Eclipse, at the moment. If you're a Spring user, and in particular if you want a guaranteed stable integration for development with Roo, no Eclipse distribution can offer you more than the SpringSource Tool Suite.

You can download the IDE from http://www.springsource.com/products/sts. It is not open-source, but it is free of cost ("as in beer"). The SpringSource Tool Suite integrates all the Eclipse plug-ins you would typically download and set up manually if you were to download the stock install of the Java EE edition of Eclipse. So, from that perspective, this is a compelling download all by itself, regardless of whether or not you plan on using Spring Roo: it's got Maven, Subversion, unmatched Spring support, enterprise OSGi, support for all of SpringSource's deployment targets (above and beyond stock adapters like Tomcat and JBoss) and much, much more.

You need Spring Roo itself. If you've downloaded the SpringSource Tool Suite, then you already have Spring Roo in the folder adjacent to the folder in which the IDE lives. If you simply wish to upgrade Roo independent of SpringSource Tool Suite or wish to use Roo with another tooling option, proceed reading this.

Visit http://www.springsource.org/roo for a plethora of information, helpful tutorials, and, of course, the distribution. While all the SpringSource projects are easy to get into—owing in large part to their excellent, world-class documentation—Spring Roo particularly excels at providing a compelling out-of-the-box developer experience. If, by chance, there is any question about how to do something even after reading this chapter (perish the thought!), you'll find ample resources on this site. To set up Roo, follow these steps:

Now, you're ready to get to the business of building your application! Launch a shell instance and then launch the SpringSource Tool Suite by executing the STS binary in the SpringSource Tool Suite folder.

If you've used Maven before, you will know that the directory structure is consistent for all Maven projects, and it's shown in Table 12-1.

Maven projects are described by the pom.xml file in the root of the project. They store metadata about the dependencies required in the application, as well as their scope: .jar files that are required only for unit testing are not included in the final build intended for deployment. Similarly, .jar files that provide interfaces needed only at compile time, such as the Spring Roo aspects (since the Spring Roo annotations are source-level only) and the various standard interfaces (you need to compile against javax.servlet.*, for example, but your deployment server already has those libraries on its path and there's no need to furnish them.)

Maven builds, much like Roo, work on the notion of convention-over-configuration. You only need to modify the Maven pom.xml file when you want to augment or change some existing behavior in the build. A minimal pom.xml is fully functional, however.

Maven already knows how to compile, deploy, document, run tests for, and share your project artifacts for you. It exposes life cycle hooks like compile, test, and so on. Plug-ins can be written to hook into those life cycle phases for different types of projects. There are defaults, however. For a standard .jar file, you don't need to specify any of these plug-ins. If you invoke a plug-in that exists in a specific phase, Maven will run all earlier phases and then invoke that plug-in. Thus, to build a working .jar of your Maven application, run the following command in the same folder as the pom.xml file lives for your project:

mvn package

This will invoke the compiler phase, the test phase, and so on, and finally the package plug-in. The package plug-in will generate a .jar file that lives in the target folder of your project (all outputs, including code generation, will live somewhere in this folder). Spring Roo also lets you perform certain operations using Maven from within the Roo shell. To package the project using the Roo shell, launch it again (using roo.sh), and invoke the following command:

$ roo> perform package

When you are using Spring Roo, there's almost no reason to directly modify the Maven pom.xml file if you don't wish to. However, it doesn't hurt to understand what Spring Roo has done for us. Open up the pom.xml file in your favorite text editor. You'll note that it has imported standard .jar files like JUnit 4.x, Apache Commons Logging, AspectJ, and the Java Servlet APIs. It has also declared a dependency on many Spring framework libraries like the core, AOP support, transaction support and test support. More than likely, you would have added most of these to your own Spring project, whether you're using Spring Roo or not. In addition, you'll note a solitary Spring Roo–specific dependency:

<dependency>
                <groupId>org.springframework.roo</groupId>
                <artifactId>org.springframework.roo.annotations</artifactId>
                <version>1.0.2.RELEASE</version>
                <scope>provided</scope>
        </dependency>

The scope is provided, which simply means it won't exist at runtime and is there only for the compiler. Spring Roo has no runtime footprint at all.

We've created our project using the shell. STS also provides a fast and convenient way to bootstrap a new Spring Roo project.

You should have a new project. Go to the Eclipse Project Explorer. Your project should be very similar to the project you created on the command line.

SpringSource Tool Suite provides a shell to let you interact with Roo from within the IDE environment. To use it, go to Window

Figure 12.2. The Spring Roo shell from within STS

Here, you may enter the same commands as you did on the command line to proceed. Note that when entering commands in the STS shell, use Ctrl + space bar, not Tab, to get auto-completion and suggestions. Ctrl + space bar is used because it's more consistent with a developer's expectations for auto-completion when in Eclipse, whereas Tab is more consistent within a terminal (Bash provides tab completion, for example).

You should have a freshly created Spring Roo application to follow along. If you haven't already done so, in either STS or on the command line, start the Roo shell (if it wasn't already running) for the project you wish to edit and update.

I think that, before we can build any kind of web application or UI layer, we need to build some sort of entity to model our records. There are many ways to do that, but for the very large majority of applications, it will involve a database and some sort of object/relational mapping (ORM) solution. That can get tedious very quickly.

If Spring Roo's so smart, let's ask it! In the Roo shell, type hint to see what to do next before we can get started. On my console, it responded:

roo> hint
Roo requires the installation of a JPA provider and associated database.

Type 'persistence setup' and then hit CTRL+SPACE three times.
We suggest you type 'H' then CTRL+SPACE to complete "HIBERNATE".
After the --provider, press CTRL+SPACE twice for database choices.
For testing purposes, type (or CTRL+SPACE) HYPERSONIC_IN_MEMORY.
If you press CTRL+SPACE again, you'll see there are no more options.
As such, you're ready to press ENTER to execute the command.

Once JPA is installed, type 'hint' and ENTER for the next suggestion.

Geez! It's a step ahead of us! It already knows we need a database and some sort of persistence mechanism. If this sort of thing carries on too long, it might give us Spring book authors a complex! Fine, enter persistence setup as it suggests. On my console, I ended up entering the following command:

roo> persistence setup --database HYPERSONIC_IN_MEMORY --provider HIBERNATE

In my project, the command created two new files (src/main/resources/META-INF/persistence.xml and src/main/resources/META-INF/spring/database.properties), and it updated two files (src/main/resources/META-INF/spring/applicationContext.xml and pom.xml).

The file src/main/resources/META-INF/spring/database.properties contains useful configuration to facilitate connection to the Hypersonic in-memory database. The pom.mxl file has been updated to contain dependencies for Hibernate and for JPA, as well as the Hypersonic embedded database .jar files. The file src/main/resources/META-INF/persistence.xml is the standard JPA configuration file to enable the Hibernate-based JPA implementation to do its work. Finally, the Spring application context, src/main/resources/META-INF/spring/applicationContext.xml, has been updated to have a data source, a JPA transaction manager, and a JPA entity manager factory.

That wasn't so bad after all! Now, we need only code a Customer entity, write a DAO and maybe a service, set up Spring MVC, add a controller, and design the UI. This should be easy. We could have a first draft up in no time—in a day or two, maximum, if we start now. Right?

I, for one, think it's fantastic that Spring Roo got us this far. It might be worth it to see if it can, by some infinitesimally small chance, get us further along and perhaps spare us the next few days' worth of development.

In the Spring Roo shell, type hint again. Here's what it said in my shell:

roo> hint
You can create entities either via Roo or your IDE.
Using the Roo shell is fast and easy, especially thanks
 to the CTRL+SPACE completion.

Start by typing 'ent' and then hitting CTRL+SPACE twice.
Enter the --class in the form '~.domain.MyEntityClassName'
In Roo, '~' means the --topLevelPackage you specified via 'create project'.

After specify a --class argument, press SPACE then CTRL+SPACE. Note nothing appears.
Because nothing appears, it means you've entered all mandatory arguments.
However, optional arguments do exist for this command (and most others in Roo).
To see the optional arguments, type '--' and then hit CTRL+SPACE. Mostly you won't
need any optional arguments, but let's select the --testAutomatically option
and hit ENTER. You can always use this approach to view optional arguments.

After creating an entity, use 'hint' for the next suggestion.
roo>

Huh! Why, Will wonders never cease?

It can help us with the entities! Right then, let's oblige it again: type ent, and press Ctrl + space bar twice. Roo should prompt you to specify a class name. Typically, the entity class should be in a subpackage of the root package. Spring Roo has a special convention, which it announces in the console message, to avoid having to retype the entire base package when specifying a class in a sub package of the application: simply use ~ in place of the entire package. If your root project was com.apress.springrecipes.test.t3, then ~ will resolve to that, and ~.domain.Customer would resolve to com.apress.springrecipes.test.t3.domain.Customer. So, the full mandatory command to generate a Customer entity, is as follows:

roo> ent --class ~.domain.Customer

However, we should also take advantage of the fact that Spring Roo can generate unit tests and integration tests for us. Let's suffix the command with the optional –testAutomatically argument. In the Spring Roo shell, to see all the optional arguments, simply type -- and then press Ctrl + space bar or Tab (for STS or the regular old Spring Roo shell, respectively) to see all the options. The command now looks like this, instead:

roo> ent --class ~.domain.Customer --testAutomatically

On my console, I can see that it added a Customer class, as expected, complete with the base JPA annotations as well as three Roo-specific annotations.

package com.apress.springrecipes.test.t3.domain;

import javax.persistence.Entity;
import org.springframework.roo.addon.javabean.RooJavaBean;
import org.springframework.roo.addon.tostring.RooToString;
import org.springframework.roo.addon.entity.RooEntity;

@Entity
@RooJavaBean
@RooToString
@RooEntity
public class Customer {
}

These annotations tell the Roo shell what services to provide to the Customer class while you're developing. Yes, you read that correctly—while you are developing! These annotations never make it past the compiler. They are there for the benefit of the Spring Roo shell, so that it knows what things you want it to help you with.

You'll note that Spring Roo also created three other files in the same package, Customer_Roo_Configurable.aj, Customer_Roo_Entity.aj, and Customer_Roo_ToString.aj. These are AspectJ ITDs. They are where Spring Roo does its magic to help you. You should not modify them. Spring Roo modifies them, and only in response to changes you make on the Customer entity. The annotations tell Spring Roo that you would like its help.

Open the Customer_Roo_ToString.aj file. In my application, the file looks like this:

package com.apress.springrecipes.test.t3.domain;

import java.lang.String;

privileged aspect Customer_Roo_ToString {

    public String Customer.toString() {
        StringBuilder sb = new StringBuilder();
        sb.append("Id: ").append(getId()).append(", ");
        sb.append("Version: ").append(getVersion());
        return sb.toString();
    }
}

It's pretty clear that this is intended to be the toString method for our Customer class, even if it is a bit strange looking. If the syntax is off-putting or confusing, don't worry. You don't need to edit these files yourself; Spring Roo modifies them for you, as you make changes to the Customer java class.

To see this effect in action, open Customer.java, and comment out the @RooToString annotation. Instantly, the Customer_Roo_ToString.aj file disappears! Uncomment the annotation, and observe that the ITD reappears instantly. Alright, I'm sure you're impressed. What happens if you write your own toString method on the Customer class? Who wins? You do, of course! Try it, and observe the ITD again disappear, deferring to your custom toString implementation first.

Remove the overridden toString implementation, for now.

If you open Customer_Roo_Entity.aj, you'll observe that Roo has already created an ID and a version field for your entity, and that it has created methods to facilitate persisting, finding, updating, and removing the entity.

Let's introduce a field. The first way we'll do so is by simply adding the filed into the Customer java class. Modify the file to look like this:

package com.apress.springrecipes.test.t3.domain;

import javax.persistence.Entity;
import org.springframework.roo.addon.javabean.RooJavaBean;
import org.springframework.roo.addon.tostring.RooToString;
import org.springframework.roo.addon.entity.RooEntity;

@Entity
@RooJavaBean
@RooToString
@RooEntity
public class Customer {
     private String name;
}

As soon as you do, you can confirm that the toString method has been updated to include the new field, and that a new ITD, called Customer_Roo_JavaBean.aj, has been introduced. This new ITD should contain the declaration of an accessor/mutator pair for the field. Convenient!

Remove the field. Let's get back to the business of letting Spring Roo do things for us. We need a few fields: a first name, a last name, and an e-mail at least. We should probably try to record the date they first bought the product and whether or not the Customer is considered still active for revenue-recognition purposes.

Spring Roo provides a command just for this scenario: the field command. Here are the commands to generate our fields. We won't hash out the gory specifics of the invocations, as they're pretty self-explanatory.

field string --fieldName firstName --notNull
field string --fieldName lastName --notNull
field string --fieldName email --notNull
field date --fieldName signupDate --type java.util.Date
field boolean --fieldName active

As you enter these, Spring Roo adds the fields to the Customer java class, complete with JSR-303 (the JSR specifying validation in the tradition of frameworks like the Hibernate Validation framework) validations, accessor/mutators, and an updated toString method. It's important to note that we aren't specifying to which entity the fields changes be applied. Spring Roo remembers what entity you last created and applies the changes to that. It has context. If you want to explicitly spell it out, use the -- entity parameter.

At this point, we have everything we need in the backend (and then some!). Let's turn our focus to building the front-end—a web application.

The goal here is to generate some simple support code that we can tune and tweak later. We'd just like to get a proof-of-concept example working. We want to build a web application that can manipulate Customer entities. We know that this would take the form of a controller in Spring MVC, so let's take a stab in the dark. Type hint controllers at the Spring Roo shell. You can see that there is indeed support for generating scaffolding controllers. Type the following command to create a Spring MVC controller that provides a UI to manipulate Customer entities (and stand back!):

controller scaff --class ~.web.CustomerController --entity ~.domain.Customer

That command packs a wallop! Our pedestrian application was just transformed from a simple service tier to a full-blown Spring MVC application with a very sane Spring MVC setup; controller support for RESTful endpoints to create, update, retrieve or delete entities; URL rewriting logic; and much more. Let's test out the application!

Let's deploy the application to a web container. If you're on the standard command line, you have a couple of options.

If you're in an IDE, you can use your IDE's support for deploying web applications. In SpringSource Tool Suite, two preconfigured servers are already available to you. Let's use the tcServer instance (which is ultimately based on Tomcat, so it should perform similarly). To do so, go to Window

Figure 12.5. This is the "Add and Remove" dialog inside of STS (or almost any Eclipse distribution with WTP support). Here, t3 is the name of my Spring Roo project.

Finally, just launch the instance by clicking on the icon with the white arrow inside a green circle; see Figure 12-6.

Figure 12.6. The Servers tab lets you launch the application from within your IDE.

When the server comes up, launch your browser and point it to http://localhost:8080/t3. Replace t3 with your application's project name.

In Figure 12-7, you can see the default welcome page for our CRM. If you click around, you'll find there is a page to create a new customer record and another to list them all. Click the "Create new Customer" link, and fill out the form to create a new Customer record. Then, click the "List all Customers" link on the left-hand side of the page to see that very record. On this page, you have the ability to update or delete the record. Paging of the results is already provided out of the box, too.

Figure 12.7. The default welcome page for your newly minted CRM

If you're astute, you will notice that the application also supports themes and is internationalized already. The application is leveraging Spring MVC's integration with Apache Tiles to support the themes and modularization, and it's leveraging Spring MVC's excellent internationalization and localization capabilities to support the various languages.

Finally, you'll note that there are RESTful endpoints that support manipulating the Customer entity.

Not bad for a minute of work!

This may not be finished enough for you, but it's definitely a good start. The project is familiar Spring MVC and Spring. There are many options from here. You can continue using Roo to add Spring Security, Spring Web Flow, and even GWT support, for example. Or you can tune the pages by hand and update the themes yourself; that's also a good option.