Chapter 1. Introduction

1.1. What is Roo?

Spring Roo is an easy-to-use productivity tool for rapidly building enterprise applications in the Java programming language. It allows you to build high-quality, high-performance, lock-in-free enterprise applications in just minutes. Best of all, Roo works alongside your existing Java knowledge, skills and experience. You probably won't need to learn anything new to use Roo, as there's no new language or runtime platform needed. You simply program in your normal Java way and Roo just works, sitting in the background taking care of the things you don't want to worry about. It's an approach unlike anything you've ever seen before, we guarantee it!

You work with Roo by loading its "shell" in a window and leaving it running. You can interact with Roo via commands typed into the shell if you like, but most of the time you'll just go about programming in your text editor or IDE as usual. As you make changes to your project, Roo intelligently determines what you're trying to do and takes care of doing it for you automatically. This usually involves automatically detecting file system changes you've made and then maintaining files in response. We say "maintaining files" because Roo is fully round-trip aware. This means you can change any code you like, at any time and without telling Roo about it, yet Roo will intelligently and automatically deal with whatever changes need to be made in response. It might sound magical, but it isn't. This documentation will clearly explain how Roo works and you'll find yourself loving the approach - just like so the many other people who are already using Roo.

Before you start wondering how Roo works, let's confirm a few things it is NOT:

  • Roo is not a runtime. Roo is not involved with your project when it runs in production. You won't find any Roo JARs in your runtime classpath or Roo annotations compiled into your classes. This is actually a wonderful thing. It means you have no lock-in to worry about (you can remove Roo from your project in just a couple of minutes!). It probably also means you won't need to get approval to use Roo (what's to approve when it's more like a command line tool than a critical runtime library like Spring Framework?). It also means there is no technical way possible for Roo to slow your project down at runtime, waste memory or bloat your deployment artefacts with JARs. We're really proud of the fact that Roo imposes no engineering trade-offs, as it was one of our central design objectives.

  • Roo is not an IDE plugin. There is no requirement for a "Roo Eclipse plugin" or "Roo IntelliJ plugin". Roo works perfectly fine in its own operating system command window. It sits there and monitors your file system, intelligently and incrementally responding to changes as appropriate. This means you're perfectly able to use vi or emacs if you'd like (Roo doesn't mind how your project files get changed).

  • Roo is not an annotation processing library. There is a Java 6 feature known as the annotation processing API. Roo does not use this API. This allows Roo to work with Java 5, and also gives us access to a much more sophisticated and extensible internal model.

So how does Roo actually work then? The answer to that question depends on how much detail you'd like. In super-summary form, Roo uses an add-on based architecture that performs a combination of passive and active code generation of inter-type declarations. If you're interested in how that works at a practical project level, we cover that shortly in the "Beginning With Roo: The Tutorial" chapter. Or for an advanced look at Roo internals, we've covered that in Part III: Internals and Add-On Development.

1.2. Why Use It

There are dozens of reasons people like to use Roo. We've worked hard to make it an attractive tool that delivers real value without imposing unpleasant trade-offs. Nonetheless, there are five major reasons why people like Roo and use it. Let's discuss these major reasons below.

1.2.1. Higher Productivity

With Roo it is possible for Java developers to build sophisticated enterprise applications in a best-practice manner within minutes. This is not just a marketing claim, but it's a practical fact you can experience yourself by trying the ten minute test.

Anyone who has programmed Java for a few years and looked at the alternatives on other platforms will be fully aware that enterprise Java suffers from productivity problems. It takes days to start a new project and incredibly long cycle times as you go about normal development. Still, we remain with Java because it's a highly attractive platform. It's the most widely used programming language on the planet, with millions of competent developers. It has first-class tooling, excellent runtime performance, numerous mature libraries and widely-supported standards. Java is also open source, has multiple vendors and countless choice.

We built Roo because we want enterprise Java developers to enjoy the same productivity levels that developers on other platforms take for granted. Thanks to Roo, Java developers can now enjoy this higher productivity plus a highly efficient, popular, scalable, open, reliable platform. Best of all, in five years time it will still be possible to hire millions of people who can look at those Roo-based projects and understand what is going on and maintain them (even if you've stopped using Roo by then).

Roo's higher productivity is provided both at original project creation, and also as a developer builds out the rest of the project. Because Roo provides round-trip support, the higher productivity is automatically provided over the full lifespan of a project. This is particularly important given the long-term maintenance costs of a project far outweigh the initial development costs. While you can use Roo just for an initial jump-start if you so wish, your return on investment is exponential as you continue using it throughout a project lifespan.

Finally, while individual productivity is important, most of us work in teams and know that someday someone else will probably maintain the code we've written. As professionals we follow architectural standards and conventions to try and ensure that our present and future colleagues will be able to understand what we did, why, and have an easy time maintaining it. Our organisations often establish standards for us to follow in an effort to ensure other projects are tackled in similar ways, thus allowing people to transfer between projects and still be productive. Of course, most organisations also have people of greatly differing backgrounds and experiences, with new graduates typically working alongside more experienced developers and architect-level experts. Roo helps significantly in this type of real-world environment because it automatically implements specific design patterns in an optimal convention-over-configuration manner. This ensures consistency of implementation within a given Roo-based project, as well as across all other Roo-based projects within an organisation (and even outside your organisation, which greatly helps with hiring). Of course, the fact Roo builds on stock-standard Java also means people of vastly different experience levels can all be highly productive and successful with Roo.

1.2.2. Stock-Standard Java

It's no longer necessary to switch platform or language to achieve extremely high levels of productivity! We designed Roo from the outset so those people with existing Java 5 knowledge, skills and experience would feel right at home. If you've ever built an enterprise application with Java, some or all of the technologies that Roo uses by default will already be familiar to you.

Some of the common technologies Roo projects use include Spring (such as Spring Framework, Spring Security and Spring Web Flow), Maven, Java Server Pages (JSP), Java Persistence API (JPA, such as Hibernate), Tiles and AspectJ. We've chosen technologies which are extremely commonly used in enterprise Java projects, ensuring you've probably either already used them or at least will have no difficulty finding hundreds of thousands of other people who have (and the resultant books, blogs, samples etc that exist for each). Also, because most of these technologies are implemented using add-ons, if you'd like Roo to use a different technology on your project it's quite easy to do so.

By using standard Java technologies, Roo avoids reinventing the wheel or providing a limited-value abstraction over them. The technologies are available to you in their normal form, and you can use them in the same way as you always have. What Roo brings to the table is automatic setup of those technologies into a Spring-certified best-practice application architecture and, if you wish, automatic maintenance of all files required by those technologies (such as XML, JSP, Java etc). You'll see this in action when you complete the ten minute test.

You'll also find that Roo adopts a very conservative, incremental approach to adding technologies to your project. This means when you first start a new project Roo will only assume you want to build a simple JAR. As such it will have next to no dependencies. Only when you ask to add a persistence provider will JPA be installed, and only when you add a field using JavaBean Validation annotations will that library be installed. The same holds true for Spring Security, Spring Web Flow and the other technologies Roo supports. With Roo you really do start small and incrementally add technologies if and when you want to, which is consistent with Roo's philosophy of there being no engineering trade-offs.

1.2.3. Usable and Learnable

There are many examples of promising technologies that are simply too hard for most people to learn and use. With Roo we were inspired by the late Jef Raskin's book, "The Humane Interface". In the book Raskin argued we have a duty to make things so easy to use that people naturally "habituate" to the interface, that text-based interfaces are often more appropriate than GUIs, and that your "locus of attention" is all that matters to you and a machine should never disrupt your locus of attention and randomly impose its idiosyncratic demands upon you.

With Roo we took these ideas to heart and designed a highly usable interface that lets you follow your locus of attention. This means you can do things in whatever order you feel is appropriate and never be subservient to the Roo tool. You want to delete a file? Just do it. You want to edit a file? Just do it. You want to change the version of Spring you're using? Just do it. You want to remove Roo? Just do it. You want to hand-write some code Roo was helping you with? Just do it. You want to use Emacs and Vim at the same time? No problem. You forgot to load Roo when you were editing some files? That's no problem either (in fact you can elect to never load Roo again and your project will remain just fine).

Because Roo uses a text-based interface, there is the normal design trade-off between learnability, expressability and conciseness. No text-based interface can concurrently satisfy all three dimensions. With Roo we decided to focus on learnability and expressability. We decided conciseness was less important given the Roo shell would provide an intuitive, tab-based completion system. We also added other features to deliver conciseness, such as contextual awareness (which means Roo determines the target of your command based on the command completed before it) and command abbreviation (which means you need only type in enough of the command so Roo recognises what you're trying to do).

The learnability of Roo is concurrently addressed on three fronts. First, we favor using standard Java technologies that you probably already know. Second, we are careful to keep Roo out of your way. The more Roo simply works in the background automatically without needing your involvement, the less you need to learn about it in the first place. This is consistent with Raskin's recommendation to never interrupt your locus of attention. Third, we offer a lot of learnability features in Roo itself. These include the "hint" command, which suggests what you may wish to do next based on your present project's state. It's quite easy to build an entire Roo project simply by typing "hint", pressing enter, and following the instructions Roo presents (we do this all the time during conference talks; it's always easier than remembering commands!). There's also the intelligent tab completion, which has natural, friendly conventions like completing all mandatory arguments step-by-step (without distracting you with unnecessary optional arguments). There's also the online "help" command, sample scripts, this documentation and plenty of other resources.

Roo also follows a number of well-defined conventions so that you always know what it's doing. Plus it operates in a "fail safe" manner, like automatically undoing any changes it makes to the file system should something go wrong. You'll quickly discover that Roo is a friendly, reliable companion on your development journey. It doesn't require special handling and it's always there for you when you need it.

In summary, we've spent a lot of time thinking about usability and learnability to help ensure you enjoy your Roo experience.

1.2.4. No Engineering Trade-Offs

Roo doesn't impose any engineering trade-offs on your project. In fact, compared with most Spring-based enterprise applications, we're almost certain you'll find a Roo application will have a smaller deployment artefact, operate more quickly in terms of CPU time, and consume less memory. You'll also find you don't miss out on any of the usual IDE services like code assist, debugging and profiling. We'll explore how Roo achieves this below, but this information is relatively advanced and is provided mainly for architects who are interested in Roo's approach. As this knowledge is not required to simply use Roo, feel free to jump ahead to the next section if you wish.

Smaller deployment artefacts are achieved due to Roo's incremental dependency addition approach. You start out with a small JAR and then we add dependencies only if you actually need them. As of Roo 1.0.0, a typical Roo-based web application WAR is around 13 Mb. This includes major components like Spring, Spring JavaScript (with embedded Dojo) and Hibernate, plus a number of smaller components like URL rewriting. As such Roo doesn't waste disk space or give you 30+ Mb WARs, which results in faster uploads and container startup times.

Speaking of startup times, Roo uses AspectJ's excellent compile-time weaving approach. This gives us a lot more power and flexibility than we'd ordinarily have, allowing us to tackle advanced requirements like advising domain objects and dependency injecting them with singletons. It also means the dynamic proxies typically created when loading Spring are no longer required. Roo applications therefore startup more quickly, as there's no dynamic proxy creation overhead. Plus Roo applications operate more quickly, as there's no dynamic proxy objects adding CPU time to the control flow.

Because Roo's AspectJ usage means there are no proxy objects, you also save the memory expense of having to hold them. Furthermore, Roo has no runtime component, so you won't lose any memory or CPU time there either. Plus because Roo applications use Java as their programming language, there won't be any classes being created at runtime. This means a normal Roo application won't suffer exhaustion of permanent generation memory space.

While some people would argue these deployment size, CPU and memory considerations are minor, the fact is they add up when you have a large application that needs to scale. With Roo your applications will use your system resources to their full potential. Plus as we move more and more enterprise applications into virtualized and cloud-hosted environments, the requirement for performant operation on shared hardware will become even more relevant.

You'll also find that Roo provides a well thought out application architecture that delivers pragmatism, flexibility and ease of maintainability. You'll see we've made architectural decisions like eliminating the DAO layer, using annotation-based dependency injection, and automatically providing dependency injection on entities. These decisions dramatically reduce the amount of Java and XML code you have to write and maintain, plus improve your development cycle times and refactoring experiences.

With Roo, you don't have to make a trade-off between productivity or performance. Now it's easy to have both at the same time.

1.2.5. Easy Roo Removal

One of the biggest risks when adopting a new tool like Roo is the ease at which you can change your mind in the future. You might decide to remove a tool from your development ecosystem for many different reasons, such as changing requirements, a more compelling alternative emerging, the tool having an unacceptable number of bugs, or the tool not adequately supporting the versions of other software you'd like to use. These risks exist in the real world and it's important to mitigate the consequences if a particular tool doesn't work out in the long-term.

Because Roo does not exist at runtime, your risk exposure from using Roo is already considerably diminished. You can decide to stop using Roo and implement that decision without even needing to change any production deployment of the application.

If you do decide to stop using Roo, this can be achieved in just a few minutes. There is no need to write any code or otherwise make significant changes. We've covered the short removal process in a dedicated removing Roo chapter, but in summary you need to perform a "push in refactor" command within Eclipse and then do a quick regular expression-based find and replace. That's all that is needed to 100% remove Roo from your project. We often remove Roo from a project during conference demonstrations just to prove to people how incredibly easy it is. It really only takes two to three minutes to complete.

We believe that productivity tools should earn their keep by providing you such a valuable service that you want to continue using them. We've ensured Roo will never lock you in because (a) it's simply the right and credible thing to do engineering-wise and (b) we want Roo to be such an ongoing help on your projects that you actually choose to keep it. If you're considering alternative productivity tools, consider whether they also respect your right to decide to leave and easily implement that decision, or if they know you're locked in and can't do much about it.

1.3. Installation

Roo is a standard Java application that is fully self-contained within the Roo distribution ZIPs. You can download Roo from one of the download sites, or build a distribution ZIP yourself from our source control repository.

If you are upgrading from an existing version of Spring Roo, you should consult the upgrade notes for important information.

Before attempting to install Roo, please ensure you have the following system dependencies:

  • A Linux, Apple or Windows-based operating system (other operating systems may work but are not guaranteed)

  • A Sun, JRocket or IBM Java 5 or Java 6 installation, with the $JAVA_HOME environment variable pointing to the installation

  • Apache Maven 2.0.9 or above installed and in the path

We have listed various considerations concerning the Java Development Kit (JDK) and operating systems in the known issues section of this documentation. We always recommend you use the latest version of Java and Maven that are available for your platform. We also recommend that you use Spring Tool Suite (STS), which is our free Eclipse-based IDE that includes a number of features that make working with Roo even easier (you can of course use Roo with normal Eclipse or without an IDE at all if you prefer).

Once you have satisfied the initial requirements, you can install Roo by following these steps:

  1. Unzip the Roo installation ZIP to a directory of your choice; this will be known as $ROO_HOME in the directions below

  2. If using Windows, add $ROO_HOME\bin to your %PATH% environment variable

  3. If using Linux or Apple, create a symbolic link using a command such as sudo ln -s $ROO_HOME/bin/ /usr/bin/roo

Next verify Roo has been installed correctly. This can be done using the following commands:

$ mkdir roo-test
$ cd roo-test
$ roo quit
    ____  ____  ____  
   / __ \/ __ \/ __ \ 
  / /_/ / / / / / / / 
 / _, _/ /_/ / /_/ /  
/_/ |_|\____/\____/    W.X.Y.ZZ [rev RRR]

Welcome to Spring Roo. For assistance press TAB or type "hint" then hit ENTER.
$ cd ..
$ rmdir roo-test

If you see the logo appear, you've installed Roo successfully. For those curious, the "[rev RRR]" refers to the Git commit ID used to compile that particular build of Roo.

1.4. Optional ROO_OPTS Configuration

The standalone Roo shell supports fine-tuning display-related configuration via the ROO_OPTS environment variable. An environment variable is used so that these configuration settings can be applied before the shell is instantiated and the first messages displayed. The ROO_OPTS settings does not apply within Spring Tool Suite's embedded Roo shell.

At present the only configuration settings available is roo.bright. This causes foreground messages in the shell to be displayed with brighter colors. This is potentially useful if your background color is light (e.g. white). You can set the variable using the following commands:

$ export ROO_OPTS="-Droo.bright=true"                   // Linux or Apple
$ set ROO_OPTS="-Droo.bright=true"                      // Windows users

There is an enhancement request within our issue tracker for customisable shell color schemes. If you're interested in seeing this supported by Roo, you may wish to consider voting for ROO-549.

1.5. First Steps: Your Own Web App in Under 10 Minutes

Now that you have installed Roo, let's spend a couple of minutes building an enterprise application using Roo.

The purpose of this application is just to try out Roo. We won't explain what's going on in these steps, but don't worry - we'll do that in the next chapter, Beginning With Roo: The Tutorial. We will try to teach you about some usability features as we go along, though.

Please start by typing the following commands:

$ mkdir ten-minutes
$ cd ten-minutes
$ roo
    ____  ____  ____  
   / __ \/ __ \/ __ \ 
  / /_/ / / / / / / / 
 / _, _/ /_/ / /_/ /  
/_/ |_|\____/\____/    W.X.Y.ZZ [rev RRR]

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've 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 for Roo help.

Notice the output from the "hint" command guides you through what to do next. Let's do that:

roo> project --topLevelPackage com.tenminutes
Created /home/balex/ten-minutes/pom.xml
Created SRC_MAIN_RESOURCES/META-INF/spring/applicationContext.xml
roo> hint
Roo requires the installation of a JPA provider and associated database.

Type 'jpa setup' and then hit TAB three times.
We suggest you type 'H' then TAB to complete "HIBERNATE".
After the --provider, press TAB twice for database choices.
For testing purposes, type (or TAB) HYPERSONIC_IN_MEMORY.
If you press TAB 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.

At this point you've now got a viable Maven-based project setup. But let's make it more useful by setting up JPA. In the interests of time, I'll just include the commands you should type below. Be sure to try using the TAB key when using the shell, as it will save you from having to type most of these commands:

roo> jpa setup --provider HIBERNATE --database HYPERSONIC_IN_MEMORY
roo> hint
roo> entity jpa --class ~.Timer --testAutomatically
roo> hint
roo> field string --fieldName message --notNull
roo> hint web mvc
roo> web mvc setup
roo> web mvc all --package ~.web
roo> selenium test --controller ~.web.TimerController
roo> perform tests
roo> perform package
roo> perform eclipse
roo> quit
$ mvn tomcat:run

The "perform" commands could have been easily undertaken from the command prompt using "mvn" instead. We just did them from within Roo to benefit from TAB completion. You could have also skipped the "perform eclipse" command if you are using the m2eclipse plugin. If you are using Spring Tool Suite (STS), it automatically includes m2eclipse and as such you do not need to use the "perform eclipse" command. Indeed if you're an STS user, you could have started your Roo project right from within the IDE by selecting the File > New > Spring Roo menu option and completing the steps. In that case a Roo Shell view will open within STS and from there you can enter the remaining commands.

Now that you've loaded Tomcat, let's run the Selenium tests. You can do this by loading a new command window, changing into the ten-minutes directory, and then executing mvn selenium:selenese. You should see your FireFox web browser execute the generated Selenium tests. You can also visit your new web application at http://localhost:8080/tenminutes, which should look similar to the picture below.

Naturally in this short ten minute test we've skipped dozens of features that Roo can provide, and didn't go into any detail on how you could have customised the application. We just wanted to show you that Roo works and you can build an application in record-time. The Beginning With Roo: The Tutorial chapter will go through the process of building an application in much more depth, including how to work with your IDE and so on.

1.6. Exploring the Roo Samples

Now that you've built your first application during the ten minute test, you have a rough idea of how Roo works. To help you learn Roo we ship several sample scripts that can be used to build new applications. These sample scripts can be found in your $ROO_HOME/classpath/src/main/resources/ directory. These sample scripts available from roo classpath. You can run any sample script by using the following command format:

$ mkdir sample
$ cd sample
$ roo
roo> script --file filename.roo
roo> quit
$ mvn tomcat:run

The filename.roo shown in the statements above should be substituted with one of the filenames from this list (note that you get filename completion using TAB):

  • clinic.roo: The Petclinic sample script is our most comprehensive. It builds a large number of entities, controllers, Selenium tests and dynamic finders. It also sets up Log4J and demonstrates entity relationships of different cardinalities.

  • vote.roo: The Voting sample script was built live on-stage during SpringOne Europe 2009, as detailed in the project history section. This is a nice sample script because it's quite small and only has two entities. It also demonstrates Spring Security usage.

  • wedding.roo: The Wedding RSVP sample script is the result of the wedding RSVP tutorial. If you're looking for another Roo tutorial, this sample script (along with the associated blog entry) is a good choice. This project includes Selenium tests, dynamic finders and Log4j configuration.

  • expenses.roo: The Expenses sample script produces a Google Web Toolkit (GWT) application using Spring Roo. This shows you the new GWT scaffolding support we added to Roo 1.1.

  • pizzashop.roo: The PizzaShop sample script demonstrates Roo's integration of JPA composite primary keys. It produces a headless application which is accessible via JSON (available through Spring MVC REST integration). To add a Web UI on top of it, simply run the web mvc all command. The application is described in greater detail in our tutorial.

1.7. Suggested Steps to Roo Productivity

As we draw to the close of this first chapter, you know what Roo is, why you'd like to use it, have installed it and completed the ten minute test, plus you know which samples are available. You could probably stop at this point and apply Roo productively to your projects, but we recommend that you spend a couple of hours learning more about Roo. It will be time well spent and easily recouped by the substantially greater productivity Roo will soon deliver on your projects.

The next step is to complete the Beginning With Roo: The Tutorial chapter. In the tutorial chapter you'll learn how to use Roo with your preferred IDE and how flexible and natural it is to develop with Roo. After that you should read the application architecture chapter to understand what Roo applications look like. From there you might wish to wrap up the recommended tour of Roo with a skim over the usage and conventions chapter. This final recommended chapter will focus more on using the Roo tool and less on the applications that Roo creates.

If you can't find the information you're looking for in this reference guide, the resources chapter contains numerous Roo-related web sites and other community resources.

We welcome your comments and suggestions as you go about using Roo. One convenient way to share your experiences is to Tweet with the @springroo hash code. You can also follow Roo's core development team via Twitter for the latest Roo updates. In any event, we thank you for exploring Roo and hope that you enjoy your Roo journey.