Introducing Spring Roo, Part 1
Building from source
Content series:
This content is part # of # in the series: Introducing Spring Roo, Part 1
This content is part of the series:Introducing Spring Roo, Part 1
Stay tuned for additional content in this series.
The Spring framework was released in late 2002 to simplify J2EE (now JavaEE) development. Over the past eight years, Spring has successfully accomplished this mission by giving the Java community frameworks or features like Spring Security, Spring MVC, transaction management, Spring batch, and Spring integration, which are easier to understand and use. Spring wanted to make a Java developer's life even easier and more productive. To make this happen, Spring created a development tool called Spring Roo.
Spring Roo (see Related topics) is an extensible, text-based open source RAD tool for Java technology. It is a powerful resource for creating and managing Spring-based applications. Here is the mission statement:
Roo's mission is to fundamentally and sustainably improve Java developer productivity without compromising engineering integrity or flexibility.
This quest translated into a tool built on Java technology, which sustainably increases productivity over the full life cycle of a project and does not lock developers into a particular approach. Spring Roo uses popular, proven, and mature libraries such as Spring framework, Java Persistence API, Java Server Pages (JSP), Spring Security, Spring Web Flow, Log4J, and Maven. The applications generated by Roo use standards like Bean Validation (JSR-303) and Dependency Injection (JSR-330), and follow best-practice SpringSource-certified application architecture.
Using Spring Roo, you can add and configure features such as JPA, Spring MVC, Spring Security, Logging using Log4j, testing frameworks like JUnit and Selenium, Solr, JMS, email, and many more, by simply typing commands on the Roo shell. The time saved using Roo to add these features increases developer productivity. Roo can't write business logic, but it can manage infrastructure or the configuration of an application.
Roo is a development-time tool, which means an application is independent of Roo at runtime. As Roo does not exist at runtime, it does not have any performance or memory overhead. This ensures that you are not tied to Spring Roo, and you can remove Roo from your project at any time in a few keystrokes.
This article discusses building a simple web application using Roo shell and demonstrates how to build the Spring Roo source code on Windows or Ubuntu machines.
Getting started with Roo shell
You can manage and configure an application by loading the Roo shell and
interacting with it using commands. Roo Shell is a tab-completing,
context-aware, hint-providing command shell. You can use the hint command
to ask Spring Roo about your next logical action. Roo is intelligent
enough to suggest the next action by determining the context of your
application. For example, let's say you have created an entity using
the entity
command. You then type the
hint
command. Roo will tell you that you should
add fields to your entity using field
. This
feature reduces the conceptual weight of Roo and makes it an excellent
learning tool. You can create the full application following Roo
help
and hint
commands without ever referring to its documentation.
Prerequisites
Before you start working with Roo, make sure you have following installed:
Installing Spring Roo
To install stand-alone Spring Roo:
- You can download Roo stand-alone command-line shell or use the built-in Roo SpringSource Tool Suite (STS) plug-in. I would suggest downloading both and using them together because STS offers many additional features over Eclipse for Spring-based applications.
- Unzip Spring Roo to the location of your choice.
- Set the environment variable:
- On a Windows machine, add %ROO_HOME% /bin to the path where ROO_HOME is the path to the unzipped Roo files.
- On a *nix machine, create a symbolic link to
$ROO_HOME/bin/roo.sh
(e.g.,
sudo ln -s ~/spring-roo-1.x.x/bin/roo.sh /usr/bin/roo
)
Building an application
To show you the power of Roo, let's create a simple enterprise conference application. A conference application has two entities: Speaker and Talk. A Speaker can give one or more talks, and Talk will be given by only one speaker. The simple class diagram is shown in Figure 1.
Figure 1. Class Diagram Speaker Talk

Create the application:
- Open your operating system command-line shell.
- Create a directory named conference using the
mkdir
command. - Go to the conference directory in your shell.
- Type roo. This command will initiate the Roo shell as shown in Listing 1.
Listing 1. Starting the Roo shell
C:\Users\xebia\demo\conference>roo ____ ____ ____ / __ \/ __ \/ __ \ / /_/ / / / / / / / / _, _/ /_/ / /_/ / /_/ |_|\____/\____/ 1.1.B.RELEASE [rev 793f2b0] Welcome to Spring Roo. For assistance press TAB or type "hint" then hit ENTER. roo>
Now that we are inside the Roo shell, we will use Roo's
hint
command to guide us through the next
steps. hint
suggests creating a new Maven-based
Spring project using project
(see Listing
2).
Listing 2. Using hint
in the Roo shell
Welcome to Spring Roo. For assistance press TAB or type "hint" then hit ENTER. roo> hint Welcome to Roo! We hope you enjoy your stay! Before you can use many features of Roo, you need to start a new project. To do this, type ’project’ (without the quotes) and then hit TAB. Enter a --topLevelPackage like ’com.mycompany.projectname’ (no quotes). When you're finished completing your --topLevelPackage, press ENTER. Your new project will then be created in the current working directory. Note that Roo frequently allows the use of TAB, so press TAB regularly. Once your project is created, type ’hint’ and ENTER for the next suggestion. You're also welcome to visit http://forum.springframework.org`for Roo help. roo>
As suggested by the hint
command, we will create a project using the
project
command. This command has one required
attribute, topLevelPackage
, to specify the name
of the root package. In addition to the required attribute, we will use
two optional attributes: java
(to specify the
Java version) and projectName
(to specify the
name of the project). Type the following:
project --topLevelPackage com.dw.roo.conference --java 6 --projectName conference
This command will create a Maven V2-managed Spring-based project as shown in the following output:
Created C:\Users\xebia\demo\conference\pom.xml Created SRC_MAIN_JAVA Created SRC_MAIN_RESOURCES Created SRC_TEST_JAVA Created SRC_TEST_RESOURCES Created SRC_MAIN_WEBAPP Created SRC_MAIN_RESOURCES\META-INF\spring Created SRC_MAIN_RESOURCES\META-INF\spring\applicationContext.xml Created SRC_MAIN_RESOURCES\log4j.properties
Again, type hint
to ask Roo for the next action. This
time it suggests setting up the persistence mechanism. Type
persistence setup
on the shell and press
Tab three times. You will obtain options for
--provider
. Press H and then
Tab to complete "HIBERNATE". After the
provider, press tab for database choices, and you will
see a number of options. Because we are using Hibernate as our provider,
we cannot choose a non-relational database like Google App Engine. For
now, we are going to use the HYPERSONIC_IN_MEMORY database.
persistence setup --provider HIBERNATE --database HYPERSONIC_IN_MEMORY
There are other optional attributes, such as username and password, which we don't need at this time.
Now that we have set up the persistence mechanism, we will again utilize
the hint
command. This time we're told to create entities using the
entity
command.
Entity
is used to create the actual domain
objects and has one required attribute,
class
, to specify the name of the entity. In addition to the
required --class
attribute, we will use the --testAutomatically
attribute,
which creates integration tests for a domain object. Let's create two
entities: Speaker and Talk.
entity --class ~.domain.Speaker –testAutomatically entity --class ~.domain.Talk --testAutomatically
I have used ~
as a placeholder for project top-level
package.
Entity
will create a flexible, feature-rich JPA
entity. The created entities will have JPA @Entity with ID, version,
EntityManager, and a no-argument constructor. The generated entity will
have methods such as persist, merge, remove, flush, count, find, and
findById, etc. If you look at the output of this command, you will notice
that this command, in addition to creating Java files (for Speaker and
Talk), also created AspectJ files ending with *Roo_*.aj. These *Roo_*.aj
are called Intertype Declaration (ITD), Mixins, or Introductions. Roo uses
ITD as a code-generation artifact. ITDs allows Roo to generate code in a
separate compilation unit, but ITDs are combined into the same compiled
class at compilation time. AspectJ intertype declarations are used to
automatically generate ID and version fields, and getters and setters for
persistence fields in domain classes.
Using hint
again provides the suggestion to
add fields to the entity using the field
command. Let's add some fields to the Speaker entity:
field string --fieldName firstname --class ~.domain.Speaker --notNull field string --fieldName lastname --notNull field string --fieldName email --unique --notNull field string --fieldName organization field date --fieldName birthdate --type java.util.Date --past --notNull field number --type java.lang.Long --fieldName age --min 25 --max 60
--class
options let us specify which class we
want to add fields to.
The field
command can be used to specify
JavaBean validation-specific
annotations with options such as --max
and
--min
, etc. It can also be used to specify
JPA-specific annotations with options like
--fetch
, --column
,
and --unique
, etc. For date fields, you can
also specify whether the date should be past or future as used above.
Using field
, you don't have to remember
these annotations.
Now let's add some fields to the Talk entity:
field string --fieldName title --class ~.domain.Talk --notNull field string --fieldName description --notNull --sizeMax 4000
So far, we have created the entities and added fields to them, but we
have not specified the relationship between them. The relationship between
Speaker and Talk is ONE_TO_MANY (i.e., one speaker can give any number of
talks). This is done using field
, as shown
below:
field set --fieldName talks --type ~.domain.Talk --class \ ~.domain.Speaker --cardinality ONE_TO_MANY field reference --fieldName speaker --type ~.domain.Speaker \ --class ~.domain.Talk –-notNull
Now we will want to scaffold a web tier for conference application.
This is done using the controller
command. The
most convenient way to generate controllers and all relevant web artifacts
is to use controller all
.
controller all --package ~.web
The first use of the controller command will also add additional dependencies, such as Spring MVC and Tiles to your project. This might take some time to run as it has to download all the dependencies (if they don't exist in your Maven repository). This command also shows one of the features of Roo: that it adds dependencies only when they are needed.
Next, we will set up the log4j using logging command:
logging setup --level INFO --package ALL_SPRING
The last thing we should do before quitting the Roo shell is run
the integration tests that were generated when we specified
--testAutomatically
with the entity
command. To run the tests from within
the shell, type perform tests
.
Roo delegates the call to Maven to run the tests, so therefore,
perform tests
is equivalent to a mvn test
command. Quit the shell by typing q or quit.
These commands will create a fully functional conference application. Next we will run this application.
To run the application, type mvn
tomcat:run
which will start the jetty server. Open a web browser and go to http://localhost:8080/conference/. You will see the screen shown
in Figure 2.
Figure 2. Conference application home page

You can click Create new Speaker to create a conference speaker. You can also view, edit, and delete a user by clicking List all Speakers. In the same way, you can create a Talk, but not before a Speaker is created.
This is a simple application, but it shows how easily you can create a new Spring-based web application from scratch in minutes. In the second part of this series, I will show you how to build an application using different Roo features and add-ons.
Now that we have created a simple application, I will show how you can build the Spring Roo source on Windows and Ubuntu.
Building Spring Roo from source
Spring Roo V1.1.0 is the latest production release version, and active development is happening under the V1.1.1 release. There are reasons why you might require building Spring Roo from source:
- Spring Roo does not provide nightly builds, so if you want the latest features of Spring Roo you need to build the source of Spring Roo.
- You want to do any sort of development for the Spring Roo project.
- You want to write an add-on for Spring Roo.
- You just want to play around with Spring Roo code to see how it is implemented or written.
Outcome
By the end of this section, you will be able to run a successful Maven build of the latest Spring Roo source code on both Windows and *nix systems. You will be able to work with the latest Spring Roo and be able to import the Spring Roo projects in Eclipse or STS (SpringSource Tool Suite).
Process for building Spring Roo source on Ubuntu
Building source code on Ubuntu (and other *nix systems) is easy. Simply follow these steps:
- Install Git, a distributed source code-control management system.
To install it on your Ubuntu system, type
sudo apt-get install git-core gitk
. - Checkout Spring Roo using Git by typing
git clone git://git.springsource.org/roo/roo.git
. You will see a roo folder in your home directory containing all of the Roo source code. - GnuPG allows encrypting and signing your data and communication, and features a versatile key-management system and access modules for all kinds of public key directories. Roo uses GPG to automatically sign build outputs.
- Fire the command
gpg --list-secret-keys
. The output should appear similar to Listing 3.Listing 3. Result of gpg list command
C:\dev\roo-sourcecode\roo>gpg --1ist-secret-keys C:/Users/xebia/AppData/Roaming/gnupg\secring.gpg sec 2048R/2F96093B 2010-07-03 uid shekhar (spring-roo) <shekhargu1ati84@gmai1.com> ssb 2048R/B77E5C63 2010-07-03 C:\dev\roo-sourcecode\roo>_
- If you don't see the output, a key must first be created. Use
gpg –gen-key
, and it will walk you through a series of steps for creating a key. Then verify that your newly created key was generated usinggpg –list-secret-keys
. - Next, you need to publish your key to a public key server. Take note
of the
sec
key ID shown from the–list-secret-keys
. In my case, it's key ID 2F96093B. Push your public key to a key server viagpg –keyserver hkp://pgp.mit.edu –send-keys 2F96093B
(change the key ID at the end). - Some Roo modules require JARs that are
not already in OSGi form. That is, they don't have an OSGi-aware
manifest. Roo has a special project called wrapping that can convert
normal JARs into OSGi JARs. You'll need to run the wrapper before
trying to work with Roo. Without the wrapper, you will see errors
stating that Maven cannot find
org.springframework.roo.wrapping.some_module
. To create the wrapped JARs, from the root Roo checkout location, type:cd wrapping mvn clean install cd..
- Next, run the
mvn clean install
command. (Maven V2 should be installed on your system. If not, install it now.) Maven will prompt you for the password/passphrase of your key (you entered the passphrase while creating GPG key) every time you build source code. Type the passphrase and press Enter. It will take a couple of minutes to build the source code.
Process for building Spring Roo source on Windows
Building source code on Windows is a bit more difficult as compared to Ubuntu. Follow these steps:
- Install Git, a distributed source code-control management system.
To start the process, you need to install Git on your windows machine.
I installed msysGit on
my Windows machine. If you already have Git installed,
you can skip this step. When you install msysGit, it will ask for an
installation location. It will open a command prompt and start firing
a lot of commands. This will continue for a minute or so.
After the install, you will see a screen as shown in Listing 4.
Listing 4. Installing msysGit
{ test "$bindir/" = "$execdir/" || \ { rm -f "$execdir/git.exe" && \ test -z "" && \ ln "$bindir/git.exe" "$execdir/git.exe" 2>/dev/null || \ cp "$bindir/git.exe" "$execdir/git.exe"; } ; } && \ { for p in git-add.exe git-annotate.exe git-apply.exe git-archive.exe git-bisect--helper.exe git-blame.exe git-branch.exe git-bundle.exe git-cat-file.exe git-check-attr.exe git-check-ref rm -f "$execdirf$p" && \ ln "Sexecdir/git.exe" "Sexecdir/$p" 2>/dev/null ll \ ln -s "git.exe" "$execdir/$p" 2>/dev/null || \ cp "Sexecdir/git.exe" "$execdir/$p" Il exit; \ done; } && \ { test x"git-renote-https.exe git-renote-ftp.exe \ git-renote-ftps.exe" = x ll \ { for p in git-remote-https.exe git-remote-ftp.exe \ git-remote-ftps.exe; do \ rm -f "$execdir{$p" && \ ln "Sexecdir/git-remote-http.exe" "$execdir/$p" 2>/dev/null ll \ ln -s “git-renote—http.exe" "$execdir/$p" 2>/dev/null || \ cp "Sexecdir/git-remote-http.exe" "Sexecdir/$p" ll exit; \ done; } ; } && \ ./check_bindir "z$bindir" "z$execdir" "Sbindir/git—add.exe" ------------------------- Hello, dear Git developer. This is a minimal MSYS environment to work on Git. You are in the git working tree, and all is ready for you to hack. Welcome to msysGit Run 'git help git' to display the help index. Run 'git help <command>' to display help for specific commands. Run '/share/msysGit/add-shortcut.tcl' to add a shortcut to msysGit. It appears that you installed msysGit using the full installer. To set up the Git repositories, please run /share/msysGit/initialize.sh
- Set the Git environment variable. Git is required to be set up in your
Windows path. Add ${MSYSGIT}\msysgit\bin and
{MSYSGIT}\msysgit\mingw\bin in your Windows path where
${MSYSGIT} is
the location where msysGit is installed. Open a new command prompt and
enter
git
. You will see the output in Figure 7.Listing 5. Git command prompt
C:\>git usage: git [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path] [-pl--paginate|I--no-pager] [--no-replace-objects] [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE] [-c name=value [--help] COMMAND [ARGS] The most commonly used git commands are: add Add file contents to the index bisect Find by binary search the change that introduced a bug branch List, create, or delete branches checkout Checkout a branch or paths to the working tree clone Clone a repository into a new directory commit Record changes to the repository diff Show changes between commits, commit and working tree, etc fetch Download objects and refs from another repository grep Print lines matching a pattern init Create an empty git repository or reinitialize an existing log Show commit logs merge Join two or more development histories together mv Move or rename a file, a directory, or a symlink pull Fetch from and merge with another repository or a local bra push Update remote refs along with associated objects rebase Forward-port local commits to the updated upstream head reset Reset current HEAD to the specified state rm Remove files from the working tree and from the index show Show various types of objects status Show the working tree status tag Create, list, delete or verify a tag object signed with GPG See ’git help COMMAND’ for more information on a specific command. C:\>_
- Checkout Spring Roo using Git. In this step, you will create a local
clone of Spring Roo by checking out the latest source using Git. Open
a command prompt and go to the location where you want to checkout
Spring Roo. Enter
git clone git://git.springsource.org/roo/roo.git
. Wait until it is finished. This will create a new folder named roo at the location where you checked out Spring Roo. - Download and install GPG for Windows. GnuPG is GNU's tool for secure
communication and data storage. It can be used to encrypt data and to
create digital signatures. Roo uses GPG to automatically sign build
outputs. Once you have installed GPG, use
gpg –list-secret-keys
. You should see output similar to Listing 6.Listing 6. Result of gpg list command
C:\dev\roo-sourcecode\roo>gpg --1ist-secret-keys C:/Users/xebia/AppData/Roaming/gnupg\secring.gpg sec 2048R/2F96093B 2010-07-03 uid shekhar (spring-roo) <shekhargu1ati84@gmai1.com> ssb 2048R/B77E5C63 2010-07-03 C:\dev\roo-sourcecode\roo>_
- If you don't see the output, it means you first need to create a
key. Use
gpg –gen-key
. It will walk you through a series of steps for creating a key. Then verify that your newly created key was generated by usinggpg –list-secret-keys
. - Publish your key to a public key server. Take note
of the
sec
key ID shown from the–list-secret-keys
. In my case, it's ID 2F96093B. Push your public key to a key server viagpg –keyserver hkp://pgp.mit.edu –send-keys 2F96093B
. (Change the key ID at the end). - Build the wrapper project first. Some Roo modules require JARs that are
not already in OSGi form. That is, they don't have an OSGi-aware
manifest. Roo has a special project called wrapping that can convert
normal JARs into OSGi JARs. You'll need to run the wrapper before
trying to work with Roo. Without the wrapper, you'll see
errors stating that Maven cannot find
org.springframework.roo.wrapping.some_module
. To create the wrapped JARs, from the root Roo checkout location, type:cd wrapping mvn clean install cd..
- Run the
mvn clean install
command. (Maven V2 should be installed on your system. If not, do so now.) It will prompt you for the password/passphrase of your key (you entered the passphrase while creating GPG key) every time you build source code. Type the passphrase and press Enter. It will take a couple of minutes to build the source code. - Set up the environment variable ROO-DEV in your system settings, which should point to the bootstrap folder within the Roo project. You should also add this variable to the PATH environment variable, as shown in Figure 3.
Figure 3. Setting up ROO-DEV variable

You can now work with the latest development version of Roo. Open the
command prompt, create a new folder called mkdir roo_dev_demo,
and fire the roo-dev
command. You will see the
screen shown in Listing 7.
Listing 7. ROO-DEV shell
C:\Users\xebia\demo\conference>roo ____ ____ ____ / __ \/ __ \/ __ \ / /_/ / / / / / / / / _, _/ /_/ / /_/ / /_/ |_|\____/\____/ 1.1.B.RELEASE [rev 793f2b0] Welcome to Spring Roo. For assistance press TAB or type "hint" then hit ENTER. roo>
You may want to update the Spring Roo source code so that you work with the
latest version of Spring Roo. Open a command prompt and go to the source
code location of Spring Roo. Fire the git pull
command, which will pull all the remote changes into your local clone, and
then do a mvn clean install
to build the updated sources.
Conclusion
At this point, we have built a simple web application without even opening our editor or referring to any documentation. The application lets you do CRUD operations on the entities. I hope you see that Roo delivers serious productivity gains to the Java developers. It uses mature and stable technologies that most developers already know.
In Part 2, we make our application more secure, add internationalization support, add messaging support (SMTP and JMS), and customize the application. We will also take a look at a database reverse-engineering feature of Roo, and convert this application to a full-featured enterprise application.
Downloadable resources
Related topics
- Learn more about Spring Roo.
- Be sure to read the rest of this Spring Roo series:
- Part 2: Developing an application with Spring Roo
- Part 3: Developing Spring Roo add-ons
- Part 4: Rapid application development in cloud with Spring Roo and Cloud Foundry
- Part 5: Write advanced and wrapper Spring Roo add-ons
- Part 6: Develop Spring MVC and GWT apps using Spring Roo 1.2 and deploy them on Cloud Foundry
- Part 7: Develop Spring MongoDB Applications using Spring Roo
- Follow developerWorks on Twitter.
- Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.