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.

To get started, please ensure you have the following system dependencies:

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) 3.7 which 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).

You can download the current release from Spring Roo project page downloads section and the related documentation.

You can also build a distribution ZIP yourself from our source control repository.

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

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

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.

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:

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.

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.

In this tutorial you will learn to create a complete Web application from scratch using Roo. The application we are going to develop will demonstrate many of the core features offered by Roo. In particular you will learn how to use the Roo shell for:

To demonstrate the development of an application using Spring Roo we will create a Web site for a Pizza Shop. The requirements for the Roo Pizza Shop application include the ability to create new Pizza types by the staff of the Roo Pizza Shop. A pizza is composed of a base and one or more toppings. Furthermore, the shop owner would like to allow online orders of Pizzas by his customers for delivery.

After this short discussion with the Pizza Shop owner, we have created a simple class diagram for the initial domain model:

While this class diagram represents a simplified model of the problem domain for the pizza shop problem domain, it is a good starting point for the project at hand in order to deliver a first prototype of the application to the Pizza Shop owner. Later tutorials will expand this domain model to demonstrate more advanced features of Spring Roo.

Now that we have spoken with our client (the Pizza Shop owner) to gather the first ideas and requirements for the project we can get started with the development of the project. After installing a JDK, Spring Roo and Maven, we create a new directory for our project:

Next, we start Spring Roo and type 'hint' to obtain context-sensitive guidance from the Roo shell:

There are quite a few usability features within the Roo shell. After typing hint you may have noticed that this command guides you in a step-by-step style towards the completion of your first project. Or if you type help you will see a list of all commands available to you in the particular context you are in. In our case we have not created a new project yet so the help command only reveals higher level commands which are available to you at this stage. To create an actual project we can use the project command:

When you used the project command, Roo created you a Maven pom.xml file as well as a Maven-style directory structure. The top level package you nominated in this command was then used as the <groupId> within the pom.xml. When typing later Roo commands, you can use the “~” shortcut key to refer to this top-level-package (it is read in by the Roo shell from the pom.xml each time you load Roo).

The following folder structure now exists in your file system:

For those familiar with Maven you will notice that this folder structure follows standard Maven conventions by creating separate folders for your main project resources and tests. Roo also installs a default application context and a log4j configuration for you. Finally, the project pom file contains all required dependencies and configurations to get started with our Pizza Shop project.

Once the project structure is created by Roo you can go ahead and install a persistence configuration for your application. Roo leverages the Java Persistence API (JPA) which provides a convenient abstraction to achieve object-relational mapping. JPA takes care of mappings between your persistent domain objects (entities) and their underlying database tables. To install or change the persistence configuration in your project you can use the jpa setup command (note: try using the <TAB> as often as you can to auto-complete your commands, options and even obtain contextual help):

So in this case we have installed Hibernate as the object-relational mapping (ORM)-provider. Hibernate is one of ORM providers which Roo currently offers. EclipseLink, OpenJPA, and DataNucleus represent the alternative choices. In a similar fashion we have chosen the Hypersonic in-memory database as our target database. Hypersonic is a convenient database for Roo application development because it relieves the developer from having to install and configure a production scale database.

When you are ready to test or install your application in a production setting, the jpa setup command can be repeated. This allows you to nominate a different database, or even ORM. Roo offers TAB completion for production databases including Postgres, MySQL, Microsoft SQL Server, Oracle, DB2, Sybase, H2, Hypersonic and more. Another important step is to edit the SRC_MAIN_RESOURCES/META-INF/persistence.xml file and modify your JPA provider’s DDL (schema management) configuration setting so it preserves the database between restarts of your application. To help you with this, Roo automatically lists the valid settings for your JPA provider as a comment in that file. Note that by default your JPA provider will drop all database tables each time it reloads. As such you’ll certainly want to change this setting.

Please note: The Oracle and DB2 JDBC drivers are not available in public maven repositories. Roo will install standard dependencies for these drivers (if selected) but you may need to adjust the version number or package name according to your database version. You can use the following maven command to install your driver into your local maven repository: mvn install:install-file -DgroupId=com.oracle -DartifactId=ojdbc14 -Dversion=10.2.0.2 -Dpackaging=jar -Dfile=/path/to/file (example for the Oracle driver)

Now it is time to create our domain objects and fields which we have identified in our class diagram. First, we can use the entity jpa command to create the actual domain object. The entity jpa command has a number of optional attributes and one required attribute which is --class. In addition to the required --class attribute we use the --testAutomatically attribute which conveniently creates integration tests for a domain object. So let’s start with the Topping domain object:

You will notice that besides the creation of Java and AspectJ sources, the entity jpa command in the Roo shell takes care of creating the appropriate folder structure in your project for the top level package you defined earlier. You will notice that we used the '~' character as a placeholder for the project’s top level package. While this serves a convenience to abbreviate long commands, you can also tab-complete the full top level package in the Roo shell.

As a next step we need to add the 'name' field to our Topping domain class. This can be achieved by using the field command as follows:

As explained in the documentation by typing the hint command you can easily add constraints to your fields by using optional attributes such as --notNull and --sizeMin 2. These attributes result in standards-compliant JSR-303 annotations which Roo will add to your field definition in your Java sources. You will also notice that the Roo shell is aware of the current context within which you are using the field command. It knows that you have just created a Topping entity and therefore assumes that the field command should be applied to the Topping Java source. Roo’s current context is visible in the shell prompt.

If you wish to add the field to a different target type you can specify the --class attribute as part of the field command which then allows you to tab complete to any type in your project.

As a next step you can create the Base and the Pizza domain object in a similar fashion by issuing the following commands (shell output omitted):

After adding the name and the price field to the Pizza domain class we need to deal with its relationships to Base and Topping. Let’s start with the m:m (one Pizza can have many Toppings and one Topping can be applied to many Pizzas) relationship between Pizza and Toppings. To create such many-to-many relationships Roo offers the field set command:

As you can see it is easy to define this relationship even without knowing about the exact JPA annotations needed to create this mapping in our Pizza domain entity. In a similar way you can define the m:1 relationship between the Pizza and Base domain entities by using the field reference command:

In a similar fashion we can then continue to create the PizzaOrder domain object and add its fields by leveraging the field date and field number commands:

This concludes this step since the initial version of the domain model is now complete.

Once you are done with creating the first iteration of your domain model you naturally want to see if it works. Luckily we have instructed Roo to create integration tests for our domain objects all along. Hint: if you have not created any integration tests while developing your domain model you can still easily create them using the test integration command. Once your tests are in place it is time to run them using the perform tests command:

As you can see Roo has issued a Maven command (equivalent to running ‘mvn test’ outside the Roo shell) in order to execute the integration tests. All tests have passed, Roo has generated 9 integration tests per domain object resulting in a total of 36 integration tests for all 4 domain objects.

Of course Roo projects can be used in your favorite IDE. We recommend the use of SpringSource Tool Suite (STS), which is available at no charge from SpringSource. If you’re not using SpringSource Tool Suite, please refer to the IDE usage section of this reference guide for a more detailed discussion of IDE interoperability.

Roo creates projects that follow standard Maven conventions. This means your IDE will be able to import your Pizza Shop project, just import it as any other Maven project. If you’re an STS user, you can import your project into STS by clicking 'File > Import > Maven > Existing Maven Projects'.

Then select the new project and build it by executing 'Project > Clean …​'.

Once your project is imported and built you can take a look at the Java sources. For example you can run the included JUnit tests by right clicking the pizzashop project and then selecting 'Run As > JUnit Test'.

As detailed in the Application Architecture chapter of this documentation Roo projects leverage AspectJ Intertype declarations extensively. This does not, however, affect your ability to use code completion features offered by STS. To see code completion working in action you can open an existing integration test and use the testMarkerMethod() method to test it. For example you can open the BaseIntegrationTest.java source file and try it out:

Note, most of the methods visible in the STS code assist are actually not in the Java sources but rather part of the AspectJ ITD and are therefore introduced into the Java bytecode at compile time.

As a next step we want to scaffold a Web tier for the Pizza Shop application. This is accomplished via the web mvc commands. The most convenient way to generate controllers and all relevant Web artifacts is to use the web mvc setup command followed by the web mvc all command:

This command will scan the Pizza Shop project for any domain entities and scaffold a Spring MVC controller for each entity detected. The --package attribute is needed to specify in which package the controllers should be installed. This command can be issued from your normal Roo shell or from the Roo shell, which ships with STS. In order to use the integrated Roo shell within STS you need to right click on the pizzashop application and select 'Spring Tools > Open Roo Shell'.

Note, that with the web mvc setup command the nature of the project changes from a normal Java project nature to a Web project nature in STS. This command will also add additional dependencies such as Spring MVC, Tiles, etc to your project. In order to update the project classpath within STS with these new dependencies you can issue 'perform eclipse' again, followed by a project refresh in STS.

All newly added Web artifacts which are needed for the view scaffolding can be found under the src/main/webapp folder. This folder includes graphics, cascading style sheets, Java Server pages, Tiles configurations and more. The purpose of these folders is summarized in the UI customization section. The Roo generated Spring MVC controllers follow the REST pattern as much as possible by leveraging new features introduced with the release of Spring Framework v3. The following URI - Resource mappings are applied in Roo generated controllers:

To deploy your application in a Web container during project development you have several options available:

After selecting your preferred deployment method you should see the Web container starting and the application should be available under the following URL http://localhost:8080/pizzashop

As discussed with the Pizza Shop owner we need to control access to certain views in the Web frontend. Securing access to different views in the application is achieved by installing the Spring Security addon via the security setup command:

Note, the Roo shell will hide the security setup command until you have created a Web layer. As shown above, the security setup command manages the project pom.xml file. This means additional dependencies have been added to the project. To add these dependencies to the STS workspace you should run the perform eclipse command again followed by a project refresh (if you’re using STS or m2eclipse, the "perform eclipse" command should be skipped as it will automatically detect and handle the addition of Spring Security to your project).

In order to secure the views for the Topping, Base, `and `Pizza resources in the Pizza Shop application you need to open the applicationContext-security.xml file in the src/main/resources/META-INF/spring folder:

As a next step you can use the Spring Security JSP tag library to restrict access to the relevant menu items in the menu.jspx file:

This leaves the pizza order view visible to the public. Obviously the delete and the update use case for the pizza order view are not desirable. The easiest way to take care of this is to adjust the @RooWebScaffold annotation in the PizzaOrderController.java source:

This will trigger the Roo shell to remove the delete and the update method from the PizzaOrderController and also adjust the relevant view artifacts.

With these steps completed you can restart the application and the 'admin' user can navigate to http://localhost:8080/pizzashop/login to authenticate.

Roo generated Web UIs can be customized in various ways. To find your way around the installed Web-tier artifacts take a look at the following table:

The easiest way to customize the look & feel of the Roo Web UI is to change CSS and image resources to suit your needs. The following look & feel was created for the specific purpose of the Pizza Shop application:

Spring Roo also configures theming support offered by Spring framework so you can leverage this feature with ease.

To achieve a higher level of customization you can change the default Tiles template (WEB-INF/layouts/default.jspx) and adjust the JSP pages (WEB-INF/views/*.jspx). WIth release 1.1 of Spring Roo jspx artifacts can now be adjusted by the user while Roo can still make adjustments as needed if domain layer changes are detected. See the JSP Views section for details.

Furthermore the Spring Roo 1.1 release introduced a set of JSP tags which not only reduce the scaffolded jspx files by 90% but also offer the most flexible point for view customization. Roo will install these tags into the user project where they can be accessed and customized to meet specific requirements of the project. For example it would be fairly easy to remove the integrated Spring JS / Dojo artifacts and replace them with your JS framework of choice. To make these changes available for installation in other projects you can create a simple add-on which replaces the default tags installed by Roo with your customized tags.

Roo offers a core addon which can generate Selenium test scripts for you. You can create the Selenium scripts by using the selenium test command. Tests are generated for each controller and are integrated in a test suite:

The generated tests are located in the src/main/webapp/selenium folder and can be run via the following maven command (executed from command line, not the Roo shell):

Running the maven selenium addon will start a new instance of the FireFox browser and run tests against the Pizza Shop Web UI by using Roo generated seed data.

Please note that the maven selenium plugin configured in the project pom.xml assumes that the FireFox Web browser is already installed in your environment. Running the maven selenium plugin also assumes that your application is already started as discussed in step 6. Finally, there are limitations with regards to locales used by the application. Please refer to the known issues section for details.

One other very useful command is the backup command. Issuing this command will create you a backup of the current workspace with all sources, log files and the script log file (excluding the target directory):

Finally, you may wish to deploy your application to a production Web container. For this you can easily create a war archive by taking advantage of the perform package command:

This command produces your war file which can then be easily copied into your production Web container.

Congratuations! You’ve now completed the Roo Pizza Shop tutorial. You’re now in a good position to try Roo for your own projects. While reading the next few chapters of this reference guide will help you understand more about how to use Roo, we suggest the following specific sections if you’d like to know more about Roo:

Spring Roo focuses on the development of enterprise applications written in Java. In the current version of Roo these applications typically will have a relational database backend, Java Persistence API (JPA) persistence approach, Spring Framework dependency injection and transactional management, JUnit tests, a Maven build configuration and usually a Spring MVC-based front-end that uses JSP for its views. As such a Roo-based application is like most modern Java-based enterprise applications.

While most people will be focusing on developing these Spring MVC-based web applications, it’s important to recognise that Roo does not impose any restrictions on the sort of Java applications that can be built with it. Even with Roo it was easy to build any type of self-contained application. Some examples of the types of requirements you can easily address with the current version of Roo include (but are not limited to):

One of the major differences between Roo and traditional, hand-written applications is we don’t add layers of abstraction unnecessarily. Most traditional Java enterprise applications will have a DAO layer, services layer, domain layer and controller layer. In a typical Roo application you’ll only use an entity layer (which is similar to a domain layer) and a web layer. As indicated by the list above, a services layer might be added if your application requires it, although a DAO layer is extremely rarely added. We’ll look at some of these layering conventions (and the rationale for them) as we go through the rest of this chapter.

Two technologies are very important in all Roo projects, those being AspectJ and Spring. We’ll have a look at how Roo-based applications use these technologies in this section.

When people use Roo, they will typically start a new project using the steps detailed in the Beginning With Roo: The Tutorial chapter. That is, they’ll start by creating the project, installing some sort of persistence system, and then beginning to create entities and add fields to them. As such, entities and fields represent the first point in a Roo project that you will be expressing your problem domain.

The role of an entity in your Roo-based application is to model the persistent "domain layer" of your system. As such, a domain object is specific to your problem domain but an entity is a special form of a domain object that is stored in the database. By default a single entity will map to a single table in your database, and a single field within your entity class will map to a single column within the corresponding table. However, like most things in Roo this is easily customised using the relevant standard (in this case, JPA annotations). Indeed most of the common customisation options (like specifying a custom column or table name etc) can be expressed directly in the relevant Roo command, freeing you from even needing to know which annotation(s) should be used.

Let’s consider a simple entity that has been created using the entity jpa command and following it with a single field command:

The above entity is simply a JPA entity that contains two fields. The two fields are annotated with JavaBean Validation API (JSR 303) annotations, which are useful if your JPA provider supports this standard (as is the case if you nominate Hibernate as your JPA provider) or you are using a Roo-scaffolded web application front end (in which case Roo will use Spring Framework 3’s JSR 303 support). Of course you do not need to use the JavaBean Validation API annotations at all, but if you would like to use them the relevant Roo field commands provide tab-completion compatible options for each. The first time you use one of these Roo field commands, Roo will add required JavaBean Validation API libraries to your project (i.e. these libraries will not be in your project until you decide to first use JavaBean Validation).

What’s interesting about the above entity is what you can actually do with it. There are a series of methods automatically added into the Choice.class courtesy of Roo code-generated and maintained AspectJ ITDs. These include static methods for retrieving instances of Choice, JPA facade methods for persisting, removing, merging and flushing the entity, plus accessors and mutators for both the identifier and version properties. You can fine-tune these settings by modifying attributes on the @RooJpaActiveRecord annotation. You can also have Roo remove these services by simply removing the @RooJpaActiveRecord annotation from the class, in which case you’ll be left with a normal JPA @Entity that you’ll need to manage by hand (e.g. provide your own persistence methods, identifier, version etc).

The @RooJavaBean annotation causes an accessor and mutator (getter and setter) to automatically be generated for each field in the class. These accessors and mutators are automatically maintained in an AspectJ ITD by Roo. If you write your own accessor or mutator in the normal .java file, Roo will automatically remove the corresponding generated method from the ITD. You can also remove the @RooJavaBean annotation if you don’t want any generated accessors or mutators (although those related to the version and identifier fields will remain, as they are associated with @RooJpaActiveRecord instead of @RooJavaBean).

Finally, the @RooToString annotation causes Roo to create and maintain a public String toString() method in a separate ITD. This method currently is used by any scaffolded web controllers if they need to display a related entity. The generated method takes care to avoid circular references that are commonly seen in bidirectional relationships involving collections. The method also formats Java Calendar objects in an attractive manner. As always, you can write your own toString() method by hand and Roo will automatically remove its generated toString() method, even if you still have the @RooToString annotation present. You can of course also remove the @RooToString annotation if you no longer wish to have a generated toString() method.

Before leaving this discussion on entities, it’s worth mentioning that you are free to create your own entity .java classes by hand. You do not need to use the Roo shell commands to create entities or maintain their fields - just use any IDE. Also, you are free to use the @RooToString or @RooJavaBean (or both) annotations on any class you like. This is especially useful if you have a number of domain objects that are not persisted and are therefore not entities. Roo can still help you with those objects.

Spring Roo can optionally provide a scaffolded Spring MVC web layer. The scaffolded MVC web layer features are explored in some depth in the Beginning With Roo: The Tutorial chapter, including how to customise the appearance. From an architectural perspective, the scaffolded layer includes a number of URL rewriting rules to ensure requests can be made in accordance with REST conventions. Roo’s scaffolding model also includes Apache Tiles, Spring JavaScript, plus ensures easy setup of Spring Security with a single command.

Scaffolded web controllers always delegate directly to methods provided on an @RooJpaActiveRecord class. For maximum compatibility with scaffolded controllers, it is recommended to observe the default identifier and version conventions provided by @RooJpaActiveRecord implementations. If you write a web controller by hand (perhaps with the assistance of the web mvc controller command), it is recommended you also use the methods directly exposed on entities. Most Roo applications will place their business logic between the entities and web controllers, with only occasional use of services layers. Please refer to the services layer section for a more complete treatment of when you’d use a services layer.

As discussed at the start of this chapter, web applications are the most common type of application created with Roo. A web application will rarely require a services layer, as most logic can be placed in the web controller handle methods and the remainder in entity methods. Still, a services layer makes sense in specific scenarios such as:

As shown, there are a large number of reasons why services layers remain valuable. However, Roo does not code generate services layers because they are not strictly essential to building a normal web application and Roo achieves separation of concern via its AspectJ ITD-based architecture.

If you would like to use a services layer, Roo offers automatic service layer integration for your application. Please refer to the service layer section in the application layering chapter for further details.

Repository layer is not generated automatically using current version of Spring Roo, but we recommed to include a Repository Layer on generated projects.

Roo offers support for different repository layers as of release 1.2.0. Please refer to the application layering chapter for details.

In future versions of Spring Roo, this layer will be generated automatically.

The jpa setup command provides the following options and attributes:

Database Options:

* The JDBC driver dependencies for these databases are not available in public Maven repositories. As such, Roo configures a default dependency in your project pom.xml. You need to adjust it according to your specific version of your database driver available in your private Maven repository.

Some useful hints to get started with Oracle Express (Oracle XE): After installing Oracle XE you need to find the JDBC driver under ${oracle-xe}/app/oracle/product/10.2.0/server/jdbc/lib and run the command:

Also, if you dont want Jetty (or Tomcat) to be conflicting with oracle-xe web-server, you should use the following command: mvn jetty:run -Djetty.port=8090.

ORM Provider Options:

In addition, the jpa setup command accepts optional databaseName, userName and password attributes for your convenience. However, it’s not necessary to use this command. You can easily edit these details in the database.properties file at any time. Finally, you can also specify a pre-configured JNDI datasource via the jndiDataSource attribute.

The jpa setup command can be re-run at any time. This means you can change your ORM provider or database when you plan to move your application between your development setup (e.g. Hibernate with HSQLDB) to your production setup (e.g. EclipseLink with DB2). Of course this is a convenience only. You’ll naturally experience fewer deployment issues if you use the same platform for both development and production.

Running the jpa setup command in the Roo shell takes care of configuring several aspects in your project:

Using the link:#command-index[entity jpa] command you can create simple Java beans which are annotated with JPA annotations. There are several optional attributes which can be used as part of this command but in its simplest form it will generate the following artifacts:

As you can see from the Roo shell messages there are 6 files generated (also, note that the context has changed to the Person type in the Roo shell):

The entity jpa command offers a number of optional (but very useful) attributes worth mentioning. For example the --testAutomatically attribute can be used to have Roo to generate and maintain integration tests for the Person type (and the persistence methods generated as part of it). Furthermore, the --abstract and --extends attributes allow you to mark classes as abstract or inheritance patterns. Of course this can also be done directly in the Java sources of the Person type but sometimes it is useful to do this through a Roo command which can be scripted and replayed if desired. Other attributes allow you to define the identifier field name as well as the identifier field type which, in turn, allows the use of complex identifier types.

As mentioned earlier in this chapter the field commands allow you to add pre-configured field definitions to your target entity type (Person.java in our example). In addition to simply adding the field names and types as defined via the command the appropriate JPA annotations are added to the field definitions. For example adding a birth day field to the Person.java type with the following command …​

You’ll notice that the @Temporal annotation is part of the JPA specification and defines how date values are persisted to and retrieved from the database in a transparent fashion. The @DateTimeFormat annotation is part of the Spring framework and takes care of printing and parsing Dates to and from String values when necessary (especially Web frontends frequently take advantage of this formatting capability).

Also note that Roo created a Person_Roo_JavaBean.aj ITD to generate accessors and mutators for the birthDay field and it also updated the toString() method to take the birthDay field into account.

Aside from the Date (and Calendar) type, the field command offers String, Boolean, Enum, Number, Reference and Set types. The Reference and Set types are of special interest here since they allow you to define relationships between your entities:

Like the entity jpa command, the field command offeres a number of optional (but very useful) attributes worth mentioning. For example, you can change the field / column name translations with the --column attribute. Furthermore there are a number of attributes which translate directly to their equivalents defined in JSR 303 (Bean Validation). These attributes include --notNull, --sizeMin, --sizeMax and other related attributes. Please refer to the field command in the appendix to review the different attributes offered.

DBRE supports most of the relational databases that can be configured for Roo-managed projects such as MySQL, MS SQL, and PostgreSQL. These drivers are auto-detected by Roo and you will be prompted by the Roo shell to download your configured database’s JDBC driver when you first issue the database introspect or database reverse engineer commands (see Section 9.3, “DBRE Add-On commands” below). For example, if you have configured your Roo project to use a PostgreSQL database, when the database introspect command is first issued, you will see the following console output:

You can get further information about the search result with the following command:

This may list several versions of a driver if available.

You can then install the latest Postgres JDBC driver by entering the following Roo command:

The JDBC driver for Postgres is immediately available for you to use. You can now enter the database introspect and database reverse engineer commands (see Section 9.3, “DBRE Add-On commands” below).

Note: currently there are no open-source JDBC drivers for Oracle or DB2 and Roo does not provide OSGi drivers for these databases. If you are an Oracle or DB2 user, you will need to obtain an OSGi-enabled driver from Oracle or IBM respectively or wrap your own Oracle or DB2 driver jars using Roo’s wrapping facility. Use the addon create wrapper to turn an existing Oracle JDBC driver into an OSGi bundle you can install into Roo. Roo does provide a wrapping pom.xml for the DB2 Express-C edition that can be used to convert your db2jcc4.jar into an OSGi-compliant driver. You can then use the osgi start command to install the jar, for example:

After you have configured your persistence layer with the jpa setup command and installed all the JDBC drivers, you can introspect and reverse engineer the database configured for your project. DBRE contains two commands:

This command displays the database structure, or schema, in XML format. The --schema is mandatory and for databases which support schemas, you can press tab to display a list of schemas from your database. You can use the --file option to save the information to the specified file.

The --enableViews option when specified will also retrieve database views and display them with the table information.

Notes:

This command creates JPA entities in your project representing the tables and columns in your database. As for the database introspect command, the --schema option is required and tab assistance is available. You can use the --package option to specify a Java package where your entities will be created. If you do not specify the --package option on second and subsequent executions of the database reverse engineer command, new entities will be created in the same package as they were previously created in.

Use the --activeRecord option to create 'Active Record' entities (default if not specified).

Use the --repository option to create Spring Data JPA Repositories for each entity. If specified as true, the --activeRecord option is ignored.

Use the --service option to create a service layer for each entity.

Use the --testAutomatically option to create integration tests automatically for each new entity created by reverse engineering.

The --enableViews option when specified will also retrieve database views and reverse engineer them into entities. Note that this option should only be used in specialised use cases only, such as those with database triggers.

You can generate non-portable JPA @Column attributes, such as 'columnDefinition' by specifying the --includeNonPortableAttributes option.

Use the --disableVersionFields option to disable the generation of 'version' fields.

Use the --disableGeneratedIdentifiers option to disable auto generated identifiers.

Since the DBRE Add-on provides incremental database reverse engineering, you can execute the command as many times as you want and your JPA entities will be maintained by Roo, that is, new fields will be added if new columns are added to a table, or fields will be removed if columns are deleted. Entities are also deleted in certain circumstances if their corresponding tables are dropped.

Examples of the database reverse engineer command:

The @RooDbManaged annotation is added to all new entities created by executing the database reverse engineer command. Other Roo annotations, @RooJpaActiveRecord, @RooJavaBean, and @RooToString are also added to the entity class. The attribute "automaticallyDelete" is added to the @RooDbManaged annotation and is set to "true" so that Roo can delete the entity if the associated table has been dropped. However, if "automaticallyDelete" is set to "false", or if any annotations, fields, constructors, or methods have been added to the entity (i.e in the .java file), or if any of the Roo annotations are removed, the entity will not be deleted.

The presence of the @RooDbmanaged annotation on an entity class triggers the creation of an AspectJ inter-type declaration (ITD) ".aj" file where fields and their getters and setters are stored matching the columns in the table. For example, if an entity called Employee.java is created by the database reverse engineer command, a file called Employee_Roo_DbManaged.aj is also created and maintained by Roo. All the columns of the matching employee table will cause fields to be created in the entity’s DbManaged ITD. An example of a DBRE-created entity is as follows:

Along with the standard entity, toString, configurable ITDs, a DbManaged ITD is created if there are more columns in the employee table apart from a primary key column. For example, if the employee table has mandatory employee name and employee number columns, and a nullable age column the ITD could look like this:

If you do not want DBRE to manage your entity any more, you can "push-in" refactor the fields and methods in the DbManaged ITD and remove the @RooDbManaged annotation from the .java file.

DBRE will produce and maintain primary key fields, including composite keys, entity relationships such as many-valued and single-valued associations, and other fields annotated with the JPA @Column annotation.

The following sections describe the features currently supported.

This section explains scenarios that may be encountered when using the DBRE feature.

With the Roo 1.2.0 release internals have been changed to allow the integration of multiple application layers. This is particularly useful for the support of different persistence mechanisms. In previous releases the only persistence supported in Roo core was the JPA Entity Active Record pattern. With the internal changes in place Roo can now support alternative persistence providers which support application layering.

While there are a number of new layering and persistence choices available, by default Roo will continue to support the JPA Active Record Entity by default (marked orange). However, you can easily change existing applications by adding further service or repository layers (details below). If you add new layers Roo will automatically change its ITDs in the consumer layer or service layer respectively. For example it will automatically inject and call a new service layer within an existing MVC controller, Integration test or data on demand for a given domain type.

There are now three options available in Roo core to support data persistence, JPA Entities (Active Record style) and JPA Repositories

Developers can also choose to create a service layer in their application. By default, Roo will create a service interface (and implementation) for one or more domain entities. If a persistence-providing layer such as Roo’s default entity layer or a repository layer is present for a given domain entity, the service layer will expose the CRUD functionality provided by this persistence layer through its interface and implementation.

As per Roo’s conventions all functionality will be introduced via AspectJ ITDs therefore providing the developer a clean canvas for implementing custom business logic which does not naturally fit into domain entities. Other common use cases for service layers are security or integration of remoting such as Web Services. For a more detailed discussion please refer to the architecture chapter.

The integration of a services layer into a Roo project is similar to the repository layer by using the @RooService annotation directly or the service command in the Roo shell:

This command will create the PizzaService interface in the defined package and additionally a PizzaServiceImpl in the same package (the name and package of the PizzaServiceImpl can be customized via the optional --class attribute).

Following Roo conventions the default CRUD method definitions can be found in the ITD:

Similarly, the PizzaServiceImpl is rather empty:

Through the AspectJ ITD the PizzaServiceImpl type is annotated with the @Service and @Transactional annotations by default. Furthermore the ITD will introduce the following methods and fields into the target type:

As you can see, Roo will detect if a persistence provider layer exists for a given domain type and automatically inject this component in order to delegate all service layer calls to this layer. In case no persistence (or other 'lower level' layer exists, the service layer ITD will simply provide method stubs.

The Web MVC addon offers a number of commands to generate and maintain various Web artifacts:

Whenever a controller is created for the first time in an application, Roo will also install an application-wide ConversionService and configure it for use in webmvc-config.xml as follows:

Spring MVC uses the ConversionService when it needs to convert between two objects types — e.g. Date and String. To become more familiar with its features we recommend that you review the (brief) sections on "Type Conversion" and "Field Formatting" in the Spring Framework documentation.

The ApplicationConversionServiceFactoryBean is a Roo-managed Java class and it looks like this:

As the comment indicates you can use the installFormatters() method to register any Converters and Formatters you wish to add. In addition to that Roo will automatically maintain an ITD with Converter registrations for every associated entity that needs to be displayed somewhere in a view. A typical use case is where entities from a many-to-one association need to be displayed in one of the JSP views. Rather than using the toString() method for that, a Converter defines the formatting logic for how to present the associated entity as a String.

In some cases you may wish to customize how a specific entity is formatted as a String in JSP views. For example suppose we have an entity called Vote. To customize how it is displayed in the JSP views add a method like this:

At this point Roo will notice that the addition of the method and will remove it from the ITD much like overriding the toString() method in a Roo entity works.

Note, in some cases you may create a form backing entity which does not contain any suitable fields for conversion. For example, the entity may only contain a field indicating a relationship to another entity (i.e. type one-to-one or one-to-many). Since Roo does not use these fields for its generated converters it will simply omit the creation of a converter for such form backing entities. In these cases you may have to provide your own custom converter to convert from your entity to a suitable String representation in order to prevent potential converter exceptions.

As mentioned in the previous section, Roo copies a number of static artifacts into the target project after issuing the controller command for the first time. These artifacts include Cascading Style Sheets, images, Tiles layout definitions, JSP files, message property files, a complete tag library and a web.xml file. These artifacts are arranged in different folders which is best illustrated in the following picture:

The i18n folder contains translations of the Web UI. The messages_XX.properties files are static resources (which will never be adjusted after the initial installation) which contain commonly used literals which are part of the Web UI. The application.properties file will be managed by Roo to contain application-specific literals. New types or fields added to the domain layer will result in new key/value combinations being added to this file. If you wish to translate the values generated by Roo in the application.properties file, just create a copy of this file and rename it to application_XX.properties (where XX represents your language abbreviation).

Roo uses XML compliant JSP files (JSPX) instead of the more common JSP format to allow round-tripping of views based on changes in the domain layer of your project. Not all jspx files in the target project are managed by Roo after the initial installation (although future addons may choose to do so). Typically jspx files in sub folders under WEB-INF/views are maintained in addition to the menu.jspx.

Here is an example of a typical roo managed jspx file (i.e.: WEB-INF/views/people/update.jspx):

You will notice that this file is fairly concise compared to a normal jsp file. This is due to the extensive use of the tag library which Roo has installed in your project in the WEB-INF/tags folder. Each tag offeres a number of attributes which can be used to customize the appearance / behaviour of the tag - please use code completion in your favourite editor to review the options or take a peek into the actual tags.

All tags are completely self-reliant to provide their functionality (there are no Java sources needed to implement specific behaviour of any tag). This should make it very easy to customize the behaviour of the default tags without any required knowledge of traditional Java JSP tag development. You are free to customize the contents of the Roo provided tag library to suit your own requirements. You could even offer your customized tag library as a new addon which other Roo users could install to replace the default Roo provided tag library.

Most tags have a few common attributes which adhere with Roo conventions to support round-tripping of the jspx artifacts. The following rules should be considered if you wish to customize tags or jspx files in a Roo managed project:

The hash key attribute is important for Roo because it helps determining if a user has altered a Roo managed element. This is the secret to round-trip support for JSPX files, as you can edit anything at any time yet Roo will be able to merge in changes to the JSPX successfully. The hash key shown in the "z" attribute is calculated as shown in the following table:

The hash code thus allows Roo to determine if the element is in its "original" Roo form, or if the user has modified it in some way. If a user changes an element, the hash code will not match and this indicates to Roo that the user has customized that specific element. Once Roo has detected such an event, Roo will change the "z" attribute value to "user-managed". This helps clarify to the user that Roo has adopted a "hands off" approach to that element and it’s entirely the user’s responsibility to maintain. If the user wishes for Roo to take responsibility for the management of a "user-managed" element once again, he or she can simply change the value of "z" to "?". When Roo sees this, it will replace the questionmark character with a calculated hash code. This simple mechanism allows Roo to easily round trip JSPX files without interfering with manual changes performed by the user. It represents a significant enhancement from Roo 1.0 where a file was entirely user managed or entirely Roo managed.

Roo will order fields used in forms in the same sequence they appear in the domain object. The user can freely change the sequence of form elements without interfering with Roo’s round tripping approach (Roo will honour user chosen element sequences as long as it can detect individual elements by their id).

The user can nest Roo managed elements in in any structure he wishes without interfering with Roo jspx round tripping. For example elements can be enclosed by HTML div or span tags to change visual or structural appearance of a page.

Most default tags installed by Roo have a render attribute which is of boolean type. This allows users to completely disable the rendering of a given tag (and potential sub tags). This is useful in cases where you don’t wish individual fields in a form to be presented to the user but rather have them autopopulated through other means (i.e. input type="hidden"). The value of the render attribute can also be calculated dynamically through the Spring Expression Language (SpEL) or normal JSP expression language. The generated create.jspx in Roo application demonstrates this.

Scaffolding of JPA reference relationships

The Roo JSP addon will read JSR 303 (bean validation API) annotations found in a form-backing object. The following convention is applied for the generation of create and update (and finder) forms:

* As mentioned above, Roo does not scaffold a HTML form element for the 'one' side of a @OneToMany relationship. To make this relationship work, you need to provide a @ManyToOne annotated field on the opposite side:

In case a field is annotated with @Pattern, the regular expression is passed on to the tag library where it may be applied through the use of the JS framework of choice.

Automatic Scaffolding of dynamic finders

Roo will attempt to scaffold Spring MVC JSP views for all dynamic finders registered in the form backing object. This is done by using the web mvc finder all or web mvc finder add command.

Due to file name length restrictions by many file systems (see http://en.wikipedia.org/wiki/Comparison_of_file_systems) Roo can only generate JSP views for finders which have 244 characters or less (including folders). If the finder name is longer than 244 characters Roo will silently skip the generation of jsp view artifacts for the dynamic finder in question). More detail can be found in ticket ROO-1027.

The add-on offers an annotation as well as two commands that support the integration of JSON support into the project’s domain layer:

Once your domain types are annotated with the @RooJson annotation, you can create Spring MVC scaffolding for your JSON enabled types.

If you need help configuring how FlexJson serializes or deserializes JSON documents, please refer to their reference documentation.

An OSGi Repository is a collection of OSGi bundles. Optionally, the repository contains an index file which reports the content of the repository along with the capabilities and requirements of each resource listed.

A repository may be located anywhere: somewhere else on the local file system; or on a remote server.

The OSGi repositories provides to Roo the capability to search, retrieve and install addons from remote servers.

Spring Roo includes a default OSGi repository (http://repo.spring.io/spring-roo/index.xml) that contains external components that could be used by developers during development.

To show all installed OSGi repositories in your Spring Roo distribution, execute:

If you are interested on install new OSGi repositories on your Spring Roo distrbution you can execute the following commands:

To remove some installed OSGi repository you can do it using addon repository remove command:

Spring Roo provides you commands to locate new available add-ons on installed OSGi repositories. To get the list of known add-ons you can use the addon repository introspect or addon search command.

For example, addon repository introspect lists all add-ons that are in the installed OSGi repositories mentioned above:

To review details about a specific add-on, use the addon info bundle which requires a "bundle symbolic name", which is usually the add-on’s top-level package. Let’s try this. To view details about the second add-on listed above, enter this command:

An example of the output of addon info bundle is shown below:

In the above output "BSN" means bundle symbolic name, which is the alternate way of referring to a given add-on. The output also shows you the Roo shell commands that are available via the add-on if have it. These commands are automatically seen by the Roo shell, so if you typed the command without first having installed the add-on, Roo would have performed a search and shown you this add-on offered the command. This is a great feature and means you can often just type commands you think you might need and find out which add-ons offer them without performing an explicit search. A similar feature exists for JDBC resolution if you try to reverse engineer a database for which there is no installed JDBC driver (Roo will automatically suggest the add-on you need and instruct you which command to use to install it).

If you decide to install a specific add-on, simply use the addon install bundle command:

Of course, you can remove add-ons as well. To uninstall any given add-on, just use the addon remove command. On this occasion we’ll use the bundle symbolic name (which is available via TAB completion as is usual with Roo):

A “Roo Addon Suite” is a great way to package and distribute a set of add-ons together, for example if you want to distribute Roo custom distributions.

Roo Addon Suite is based on OSGi R5 Subsystems that provides a really convenient deployment model, without compromising the modularity of Roo.

To know which Roo Add-On Suites are installed on your Spring Roo distribution, you could execute the following command:

All Roo Add-On Suites should be located in OSGi Repositories, so to install a new Roo Add-On Suite on your Spring Roo distribution is necessary to install an OSGi Repository as we saw above.

After install the OSGi repository that contains the Roo Add-On Suite, you could install all available Roo Add-On Suites executing the following command:

After install the selected Roo Add-On Suite, you will have available on your Spring Roo distribution all components of that Suite. If you want to stop them, you can do it executing the following command:

Note that all of the "addon" commands only work with add-ons listed in the installed OSGi Repositories. If you want to manage your installed OSGi Repositories, see OSGi Repositories section

Whether you are part of the Roo core development team, you want to contribute patches, or you want to develop add-ons there are a few guidelines we would like to bring to your attention.

We develop against a public Git repository from which you can anonymously checkout the code:

Roo itself uses Maven, so it’s very easy to build the standard package, install, assembly and site goals. PGP should be installed, see the 'Setting Up for Development' section below for details.

We maintain up-to-date documentation in the readme.txt in the root of the checkout location. Please follow these instructions carefully.

Submitting a patch for a bug, improvement or even a new feature which you always wanted addressed can be of great help to the Spring Roo project.

To get started, create new ticket on our JIRA to warn the community with your new feature, improvement or bug fix.

You could build Roo from sources (as described above), and locally start changing source code as you see fit. Then test your changes and if all works well, you can create a git patch and attach it to the JIRA ticket.

Feel free to submit a pull request at https://github.com/spring-projects/spring-roo/pulls to fix this issue.

Essentially if you submit a patch and we think it is useful to commit to the code base, we will ask you to complete our contributor agreement. This is just a simple web form that deals with issues like patents and copyrights. Once this is done, we can apply your patch to the source code repository.

Feel free to complete the online individual contributers agreement at https://support.springsource.com/spring_committer_signup so we can apply your patch.

Once you have installed Java, Maven, PGP you can change into the <project-name> directory. In the <project-name> directory, you can start the Spring Roo shell and use one of the new commands for add-on creation:

The addon create simple command will scaffold a number of artefacts:

This newly created add-on project can be imported into the STS via File > Import > Maven > Existing Maven projects. Let’s discuss some of these artefacts in more detail:

Spring Roo provides an easy way for external add-ons to contribute new commands to the Roo Shell. Looking at the code extract below, there are really only two artefacts needed in your command type to register a new command in the Roo Shell; your type needs to implement the CommandMarker interface, and you need to create a method annotated with @CliCommand. Let us review some details:

There are a few artefacts of interest when developing Spring Roo add-ons:

Almost all Spring Roo add-ons provide operations types. These types do most of the work behind Roo’s passive generation principle (active generation is taken care of by AspectJ Intertype declarations (ITDs) - more about that later). Methods offered by the operations types provided by the add-on are typically invoked by the accompanying "command" type. Alternatively, operations types can also be invoked by other add-ons (this is a rather unusual case).

Implementations of the Operations interface need to be annotated with the Felix @Component and @Service annotations to make their functionality available within Roo’s OSGi container. Dependencies can be injected into operations types via the Felix @Reference annotation. If the dependency exists in a package that is not yet registered in the add-on’s pom.xml, you need to add the dependency there to add the relevant bundle to the add-on’s classpath.

The Add-On Creator generated project includes example code which uses Roo’s source path abstractions, file manager and various Util classes that take care of project file management.

Typical functionality offered by operations types include:

Spring Roo offers a wide range of abstractions and metadata types that support these use cases. For example, the following services are offered:

In addition the org.springframework.roo.support bundle provides a number of useful utils classes:

Once your add-on is complete, you can test its functionality locally by generating an OSGi-compliant jar bundle and installing it in the Spring Roo Shell:

This will generate your add-on OSGi bundle in the project’s target directory. In a separate directory, you can start the Spring Roo Shell and use the following command to test your new add-on:

This should install and activate your new Spring Roo Add-On. For troubleshooting, Roo offers the following OSGi commands:

Once you have tested the add-on successfully in your development environment, you can release the add-on jar to your own OSGi Repository and update the Spring Roo Marketplace with yout OSGi Repository URL.

This module is a simple Spring Roo Add-On like the explained before. The only difference is that includes an obr.xml file.

This obr.xml file is really important in the new Spring Roo arquitechture. This file contains available commands of the add-on and allows Spring Roo to locate add-on on installed repositories when the developer types an add-on command that is not installed yet.

This module is an advanced Spring Roo Add-On that contains Metadatas and some annotations. As the Add-On Simple, contains an obr.xml file that contains available commands of the add-on.

This module contains only a pom.xml, and it is the responsible of configure all bundles of Spring Roo Add-On suite correctly.

Every Add-On has this bundle as parent on pom.xml.

This module contains necessary maven plugins to generate an OSGi Subsystem in .esa file with all required add-ons.

This module generates an OSGi Repository ready to distribute your Roo Addon Suite in your own server after compile.

This generated Spring Roo Add-On Suite contains "suite-dev" file, that allows you to test your generated Roo Add-On Suite using an Spring Roo 2.0+.

After develop your own Roo Addon Suite or your own Add-On, you could publish it in your own server using an OSGi Repository as we saw in the point above.

To include your own OSGi Repository on Spring Roo Marketplace page, just send a pull request with the addition to Spring Roo repo’s gh-pages branch (roo_addons_suites.html file).

Install some 'Roo Addon Suite' from installed OBR Repository

Install some 'Roo Addon Suite' from URL

Lists all installed 'Roo Addon Suite'. If you want to list all available 'Roo Addon Suites' on Repository, use --repository parameter

Start some installed 'Roo Addon Suite'

Stop some started 'Roo Addon Suite'

Uninstall some installed 'Roo Addon Suite'

Backup your project to a zip file

This command does not accept any options.

Creates a new Java class source file in any project path

Creates a class constructor

Inserts a new enum constant into an enum

Creates a new Java enum source file in any project path

Changes focus to a different type

Creates a new Java interface source file in any project path

Setup Cloud Provider on Spring Roo Project

Scaffold controllers for all project entities without an existing controller - deprecated, use 'web mvc setup' + 'web mvc all' instead

Create a new scaffold Controller (ie where we maintain CRUD automatically) - deprecated, use 'web mvc scaffold' instead

Scaffold Spring MVC controllers for all project entities without an existing controller

Create a new scaffold Controller (ie where Roo maintains CRUD functionality automatically)

Create a new advanced add-on for Spring Roo (commands + operations
metadata + trigger annotation + dependencies)

Create a new Internationalization add-on for Spring Roo

Create a new simple add-on for Spring Roo (commands + operations)

Create a new Spring Roo Addon Suite for Spring Roo (two sample addons
repository + suite generator)

Create a new add-on for Spring Roo which wraps a maven artifact to create a OSGi compliant bundle

Creates a new data on demand for the specified entity

Displays database metadata

Create and update entities based on database metadata

Embed a document for your WEB MVC application

Embed media by URL into your WEB MVC application

Embed a map for your WEB MVC application

Embed a photo gallery for your WEB MVC application

Embed a video stream into your WEB MVC application

Embed twitter messages into your WEB MVC application

Embed a video for your WEB MVC application

Embed Google wave integration for your WEB MVC application

Add equals and hashCode methods to a class

Passes a command directly through to the Felix shell infrastructure

Exits the shell

This command does not accept any options.

Adds a private boolean field to an existing Java source file

Adds a private date field to an existing Java source file

Adds a private @Embedded field to an existing Java source file

Adds a private enum field to an existing Java source file

Adds a byte array field for storing uploaded file contents (JSF-scaffolded UIs only)

Adds a private List field to an existing Java source file (eg the 'one' side of a many-to-one)

Adds a private numeric field to an existing Java source file

Inserts a private field into the specified file

Adds a private reference field to an existing Java source file (eg the 'many' side of a many-to-one)

Adds a private Set field to an existing Java source file (eg the 'one' side of a many-to-one)

Adds a private string field to an existing Java source file

Install finders in the given target (must be an entity)

List all finders for a given target (must be an entity)

Shows system help

Writes the reference guide XML fragments (in DocBook format) into the current working directory

This command does not accept any options.

Provides step-by-step hints and context-sensitive guidance

Creates a new integration test for the specified entity

Creates a mock test for the specified entity

Creates a test stub for the specified class

Displays the local date and time

This command does not accept any options.

Parses the specified resource file and executes its commands

Shows the shell’s properties

This command does not accept any options.

Displays shell version

Insert a JmsOperations field into an existing type

Create an asynchronous JMS consumer

Install a JMS provider into your project

Shows database configuration details

This command does not accept any options.

Removes a particular database property

Changes a particular database property

Creates a new Java class source file with the JPA @Embeddable annotation in SRC_MAIN_JAVA

Creates a new JPA persistent entity in SRC_MAIN_JAVA

Install or updates a JPA persistence provider in your project

Install or updates a JPA persistence provider in your project - deprecated, use 'jpa setup' instead

Adds @RooJson annotation to target type

Adds @RooJson annotation to all types annotated with @RooJavaBean

Create a new manual Controller (ie where you write the methods) - deprecated, use 'web mvc controller' instead

Create a new manual Controller (ie where you write the methods)

Install new internationalization bundle for MVC scaffolded UI.

Create a new static view.

Install new internationalization bundle for MVC scaffolded UI.

Setup a basic project structure for a Spring MVC / JSP application

This command does not accept any options.

Replace an existing application tagx library with the latest version (use --backup option to backup your application first)

Create a new static view.

Configure logging in your project

Install a Spring JavaMailSender in your project

Configures a template for a SimpleMailMessage

Inserts a MailTemplate field into an existing type

Adds a new dependency to the Maven project object model (POM)

Removes an existing dependency from the Maven project object model (POM)

Adds a new repository to the Maven project object model (POM)

Removes an existing repository from the Maven project object model (POM)

Creates a new Maven module

Changes focus to a different project module

Executes the assembly goal via Maven

This command does not accept any options.

Executes a full clean (including Eclipse files) via Maven

This command does not accept any options.

Executes a user-specified Maven command

Sets up Eclipse configuration via Maven (only necessary if you have not installed the m2eclipse plugin in Eclipse)

This command does not accept any options.

Packages the application using Maven, but does not execute any tests

This command does not accept any options.

Executes the tests via Maven

This command does not accept any options.

Shows detailed metadata for the indicated type

Shows detailed information about the metadata item

Shows the ProjectMetadata for the indicated project module

Shows detailed metadata for the indicated type

Shows metadata statistics

This command does not accept any options.

Traces metadata event delivery notifications

Provide information about a specific Spring Roo Add-on

Install Spring Roo Add-on

Install Spring Roo Add-on using url

List all installed addons

This command does not accept any options.

Remove Spring Roo Add-on

Search all known Spring Roo Add-ons

Adds a new OBR Repository to ROO Shell

Introspects all installed OBR Repositories and list all their addons

This command does not accept any options.

Lists existing OBR Repositories

This command does not accept any options.

Removes an existing OBR Repository from ROO Shell

Indicates to automatically trust all keys encountered until the command is invoked again

This command does not accept any options.

Downloads a remote key and displays it to the user (does not change any trusts)

Lists the keys you currently trust and have not been revoked at the time last downloaded from a public key server

This command does not accept any options.

Refreshes all keys from public key servers

This command does not accept any options.

Displays the status of the PGP environment

This command does not accept any options.

Grants trust to a particular key ID

Revokes your trust for a particular key ID

Indicates if process manager debugging is desired

Switches the system into development mode (greater diagnostic information)

Perform a manual file system scan

This command does not accept any options.

Changes the file system scanning speed

Display file system scanning information

This command does not accept any options.

Creates a new Maven project

Shows the details of a particular properties file

Removes a particular properties file property

Changes a particular properties file property

Adds @RooJpaRepository annotation to target type

Create a permission evaluator

Install Spring Security into your project

This command does not accept any options.

Creates a new Selenium test for a particular controller

Adds @RooService annotation to all entities

Adds @RooService annotation to all entities with options for authentication, authorization, and a permission evaluator

Adds @RooService annotation to target type with options for authentication, authorization, and a permission evaluator

Adds @RooService annotation to target type

Activate a tailor configuration.

Deactivate the tailor.

This command does not accept any options.

List available tailor configurations.

This command does not accept any options.

Adds @RooWebFinder annotation to MVC controller type

Adds @RooWebFinder annotation to existing MVC controllers

This command does not accept any options.

Adds @RooJson annotation to target type

Adds or creates MVC controllers annotated with @RooWebJson annotation

Set up Spring MVC to support JSON

This command does not accept any options.

As mentioned in earlier chapters and is easily experienced by simply using Spring Roo for a project, we placed a great deal of emphasis on usability during Roo’s design. It is our experience that a normal enterprise Java developer is able to pass the ten minute test with Roo and build a new project without referring to documentation. There are several conventions that we use within Roo to ensure a highly usable experience:

The last two points are what we’re going to discuss in this section.

Making sure Roo works the way you would expect it to is reflected in a number of key design decisions that basically boil down to "you can do whatever you want, whenever you want, and Roo will automatically work in with you". There are obviously limits to how far we can take this, but as you use Roo you’ll notice a few operational conventions that underpin this.

Let’s start by looking at file conventions. Roo will never change a .java file in your project unless you explicitly ask it to via a shell command. In particular, Roo will not modify a .java file just because you apply an annotation. Roo also handles .xml files in the same manner. There are only two file types that may be created, updated or deleted by Roo in an automatic manner, those being .jspx files and also AspectJ files which match the *_Roo_*.aj wildcard.

In terms of the AspectJ files, Roo operates in a very specific manner. A given AspectJ filename indicates the "target type" the members will be introduced into and also the add-on which governs the file. Roo will only ever permit a given AspectJ file to be preserved if the target type exists and the corresponding add-on requests an ITD for that target type. Nearly all add-ons will only create an ITD if there is a "trigger annotation" on the target type, with the trigger annotation always incorporating an @Roo prefix. As such, if you never put any @Roo annotation on a given .java file, you can be assured Roo will never create any AspectJ ITD for that target type. Refer to the file system conventions section for related information.

You’ll also notice when using Roo that it automatically responds to changes you make outside Roo. This is achieved by an auto-scaling file system monitoring mechanism. This basically allows you to create, edit or delete any file within your project and if the Roo shell is running it will immediately detect your change and take the necessary action in response. This is how round-tripping works without you needing to include Roo as part of your build system or undertake any crude mass generation steps.

What happens if the Roo shell isn’t running? Will there be a problem if you forget to load it and make a change? No. When Roo starts up it performs a full scan of your full project file system and ensures every automatically-managed file that should be created, updated or deleted is handled accordingly. This includes a full in-memory rebuild of each file, and a comparison with the file on disk to detect changes. This results in a lot more robust approach than relying on relatively coarsely-grained file system timestamp models. It also explains why if you have a very big project it can take a few moments for the Roo shell to startup, as there is no alternative but to complete this check for actions that happened when Roo wasn’t running.

The automated startup-time scan is also very useful as you upgrade to newer versions of Roo. Often a new version of Roo will incorporate enhancements to the add-ons that generate files in your project. The startup-time scan will therefore automatically deliver improvements to all generated files. This is also why you cannot edit files that Roo is responsible for managing, because Roo will simply consider your changes as some "old format" of the file and rewrite the file in accordance with its current add-ons.

Not being able to edit the generated files may sound restrictive, as often you’ll want to fine-tune just some part of the file that Roo has emitted. In this case you can either write a Roo add-on, or more commonly just write the method (or field or constructor etc) directly in your .java file. Roo has a convention of detecting if any member it intends to introduce already exists in the target type, and if it does Roo will not permit the ITD to include that member. In plain English that means if you write a method that Roo was writing, Roo will remove the method from its generated file automatically and without needing an explicit directive to do so. In fact the Roo core infrastructure explicitly detects buggy add-ons that are trying to introduce members that an end user has written and it will throw an exception to prevent the add-on from doing so.

This talk of exceptions also lets us cover the related usability feature of being forgiving. Every time Roo changes your file system or receives a shell command, it is executed within a quasi-transactional context that supports rollback. As a result, if anything goes wrong (such as you made a mistake when entering a command or an add-on has a problem for whatever reason) the file system will automatically rollback to the state it was before the change was attempted. The cascading nature of many changes (i.e. you add a field to a .java file and that changes an AspectJ ITD and that in turn changes a web .jspx etc) is handled in the same unit of work and therefore rolled back as an atomic group when required.

Before leaving this discussion on usability, it’s probably worth pointing out that although the Roo shell contains numerous commands, you don’t need to use them. You are perfectly free to perform any change to your file system by hand (without the help of the Roo shell). For example, there are commands which let you create .java files or add fields to them. You can use these commands or you can simply do this within your IDE or text editor. Roo’s automatic file system monitoring will detect the changes and respond accordingly. Just work the way you feel most comfortable - Roo will respect it.

Many people who first look at Roo love the shell. In fact when we first showed Roo to an internal audience, one of the developers present said tounge-in-cheek, "That could only have come from someone with a deep love of the Linux command line!". All jokes aside, the shell is only one part of the Roo usability story - although it’s a very important part. Here are some of the usability features that make the shell so nice to work with:

The scripting and script recording features are particularly nice, because they let you execute a series of Roo commands without typing them in.

To execute a Roo script, just use the script command. When you use the script command you’ll need to indicate the script to run. We ship a number of sample scripts with Roo, as discussed earlier in the Exploring Roo Samples section.

What if you want to create your own scripts? All you need is a text editor. The syntax of the script is identical to what you’d type at the Roo shell. Both the Roo shell and your scripts can contain inline comments using the ; and // markers, as well as block comments using the /* */ syntax.

A really nice script-related feature of the Roo shell is that it will automatically build a script containing the commands you entered. This file is named log.roo and exists in your current working directory. Here’s a quick example of the contents:

In the recorded script, you can see the version number, session start time and session close times are all listed. Also listed is a command I typed that was intentionally incorrect, and Roo has turned that command into a comment within the script (prefixed with // [failed]) so that I can identify it and it will not execute should I run the script again later. This is a great way of reviewing what you’ve done with Roo, and sharing the results with others.

Despite Roo’s really nice shell, in reality most people develop most of their application using an IDE or at least text editor. Roo fully expects this usage and supports it.

Before we cover how to use an IDE, it’s worth mentioning that you don’t strictly need one. With Roo you can build an application at the command line, although to be honest you’ll get more productivity via an IDE if it’s anything beyond a trivial application. If you would prefer to use the command line, you can start a fresh application using the Roo shell, edit your .java and other files using any text editor, and use the perform commands to compile, test and package your application ready for deployment. You can even use mvn tomcat:run to execute a servlet container. Again, you’ll be more productive in an IDE, but it’s nice to know Roo doesn’t force you to use an IDE unless you’d like to use one.

In relation to IDEs, we highly recommend that you use SpringSource Tool Suite (STS). STS is a significantly extended version (and free!) of the pervasive Eclipse IDE. From a Roo perspective, STS preintegrates the latest AspectJ Development Tools (AJDT) and also offers Roo shell as extension plugin.

The STS Roo shell means you do not need to run the normal Roo shell if you are using STS. You’ll also have other neat Roo-IDE integation features, like the ability to press CTRL+R (or Apple+R if you’re on an Apple) and a popup will allow you to type a Roo command from anywhere within the IDE. Another nice feature is the shell message hotlinking, which means all shell messages emitted by Roo are actually links that you can click to open the corresponding file in an Eclipse editor.

Naturally Roo works well with standard Eclipse as well. All you need to do is ensure you install the latest AspectJ Development Tools (AJDT) plugin. This will ensure code assist and incremental compilation works well. We also recommend you go into Window > Preferences > General > Workspace and switch on the "Refresh automatically" box. That way Eclipse will detect changes made to the file system by the externally-running Roo shell. It’s also recommended to install the m2eclipse plugin, which is automatically included if you use STS and is particularly suitable for Roo-based projects.

When using AJDT you may encounter a configuration option enabling you to "weave" the JDT. This is on by default in STS, so you’re unlikely to see the message if using STS. If you are prompted (or locate the configuration settings yourself under the Window > Preferences > JDT Weaving menu), you should enable weaving. This ensures the Java Editor in Eclipse (or STS) gives the best AspectJ-based experience, such as code assist etc. You can also verify this setting is active by loading Eclipse (or STS) and selecting Window > Preferences > JDT Weaving.

If you’re using m2eclipse, you won’t need to use the perform eclipse command to setup your environment. A simple import of the project using Eclipse’s File > Import > General > Maven Projects menu option is sufficient.

Irrespective of how you import your project into Eclipse (i.e. via the perform eclipse command or via m2eclipse) you should be aware that the project will not be a Web Tools Project (WTP) until such time as you install your first web controller. This is usually undertaken via the web mvc all or web mvc controller command. If you have already imported your project into Eclipse, simply complete the relevant web mvc command and then re-import. The project will then be a WTP and offer the ability to deploy to an IDE-embedded web container. If you attempt to start a WTP server and receive an error message, try right-clicking the project and selecting Maven > Update Project Configuration. This often resolves the issue.

If you’re using IntelliJ, we are pleased to report that IntelliJ now supports Roo. This follows the completion of ticket IDEA-26959, where you can obtain more information about the AspectJ support now available in IntelliJ.

If you’re using any IDE other than STS, the recommended operating pattern is to load the standalone Roo shell in one operating system window and leave it running while you interact with your IDE. There is no formal link between the IDE and Roo shell. The only way they "talk" to each other is by both monitoring the file system for changes made by the other. This happens so quickly that you’re unlikely to notice, and indeed internally to Roo we have an API that allows the polling-based approach to be replaced with a formal notification API should it ever become necessary. As discussed in the usability section, if you forget to load the Roo shell and start modifying your project anyway, all you need to do is load the Roo shell again and it will detect any changes it needs to make automatically.

Roo currently supports the use of Apache Maven. This is a common build system used in many enteprise applications. We routinely poll our community and look at public surveys which consistently show that nearly all enterprise development projects use either Maven or Ant, so we believe this is a good default for Roo projects. As per the installation instructions, you must ensure you are using Maven 3.0.5 or above. We do recommend you use last version of Maven for best results, though.

Roo will create a new pom.xml file whenever you use the project command. The POM will contain the following Roo-specific considerations:

There are no other Roo changes to the POM. In particular, there is no requirement for the POM to include Roo as part of any code generation step. Roo is never used in this "bulk generation style".

If you are interested in ensuring a build includes the latest Roo code generation output, you can cause Maven or equivalent build system to execute roo quit. The presentation of the quit command line option will cause the Roo shell to load, perform its startup-time scan (which identifies and completes any required changes to generated files) and then exit.

Those seeking Ant/Ivy instead of Maven support are encouraged to vote for issue ROO-91. The internals of Roo do not rely on Maven at all. Nonetheless we have deferred it until we see sufficient community interest to justify maintaining two build system environments.

We have already covered some of Roo’s file system conventions in the Usability Philosophy section. In summary Roo will automatically monitor the file system for changes and code generate only those files which match the *_Roo_*.aj wildcard. It will also code generate those JSPs associated with scaffolded MVC controllers that have the annotation @RooWebScaffold.

Roo applications follow the standard Maven-based directory layout. We have also placed Spring application context-related files (both .xml and .properties) in the recommended classpath sub-directory for Spring applications, META-INF/spring.

Roo supports the installation and removal of third-party add-ons. Roo added significant enhancements to its add-on model, as more thoroughly discussed in Part III of this manual.

Following some simple recommendations will ensure you have the best possible experience with Roo:

If you have an existing project that you’d like to use with Roo, we recommend that you follow these steps:

If you encounter any difficulty, we recommend you consult the Roo Resources section of the reference guide for help.

Many organisations have existing databases that they’d like to use with Roo.

A significant new feature added to Spring Roo 1.1 was support for incremental database reverse engineering. This feature is robust and comprehensive, and allows you to reverse engineer an existing database in a single command. The single command doesn’t even ask you any questions as it operates, and it gracefully handles changes to your schema over time.

We recommend that you consult the incremental database reverse engineering chapter if you’d like to work with an existing relational database.

At the time we created the mission statement for Roo, a key dimension was "without compromising engineering integrity or flexibility". To us that meant not imposing an unacceptable burden on projects like forcing them to use the Roo API or runtime or locking them in. While it complicated our design to achieve this, we’re very proud of the fact Roo’s approach has no downside at runtime or lock-in or future flexibility. You really can have your cake and eat it too, to reflect on the common English expression.

Roo avoids locking you in by adopting an active code generation approach, but unlike other code generators, we place Roo generated code in separate compilation units that use AspectJ inter-type declarations. This is vastly better than traditional active code generation alternatives like forcing you to extend a particular class, having the code generator extend one of your classes, or forcing you to program a model in an unnatural diagrammatic abstraction. With Roo you just get on with writing Java code and let Roo take care of writing and maintaining the code you don’t want to bother writing.

The other aspect of how Roo avoids lock-in is using annotations with source-level retention. What this means is the annotations are not preserved in your .class files by the time they are compiled. This in turn means you do not need the Roo annotation library in your runtime classpath. If you look at your `WEB-INF/lib `directory (if you’re building a web project), you will find absolutely no Roo-related JARs. They simply don’t exist. In fact if you look at your development-time classpath, only the Roo annotation JAR library will be present - and that JAR doesn’t contain a single executable line of code. The entire behaviour of Roo is accomplished at development time when you load the Roo shell. If you also think about the absence of executable code anywhere in your project classpath, there is no scope for possible Roo bugs to affect your project, and there is no risk of upgrading to a later version of Roo.

Because we recommend people check their Roo-generated *_Roo_*.aj files into source control, you don’t even need to load Roo to perform a build of your project. The source-level annotation library referred to in the previous paragraph is in a public Maven repository and will automatically be downloaded to your computer if it’s not already present. This means Roo is not part of your build process and your normal source control system branching and tagging processes will work.

This also means that a project can "stop using Roo" by simply never loading the Roo shell again. Because the *_Roo_*.aj files are written to disk by the Roo shell when it last ran, even if it’s never loaded again those files will still be present. The removal procedures in this chapter therefore focus on a more complete removal, in that you no longer even want the *_Roo_*.aj files any more. That said, there’s nothing wrong with just never loading Roo again and keeping the *_Roo_*.aj files. The only possible problem of adopting the "never load Roo again" approach is that someone might load Roo again and those files will be updated to reflect the latest optimisations that Roo can provide for you.

By removing Roo, you eliminate the Roo-generated source files from your project. These are inter-type declarations stored in *_Roo_*.aj files. You also remove the Roo annotation library from your project. This might be attractive if you’ve made a decision to no longer use Roo for some reason, or you’d like to ship the finished project to your client and they’d prefer a simple Java project where every piece of code is in standard .java files. Another reason you might like to remove Roo is to simply satisfy yourself it’s easy to do so and therefore eliminate a barrier to adopting Roo for real projects in the first place.

Even though it’s easy to do so, there are downsides of removing Roo from your project:

As such we believe using Roo and continuing to use Roo makes a lot of sense. But if you’re willing to accept the trade-offs of removing Roo (which basically means you switch to writing your project the unproductive "old fashioned way"), you can remove Roo very easily. Don’t forget when in doubt you can always defer the decision. It’s not as if Roo won’t let you remove it just as easily in six months or two years from now!

The following instructions explain how to remove Spring Roo from one of your projects that has to date been using Roo. Naturally if you’d simply like to remove Roo from your computer (as opposed to from an existing project), the process is as simple as removing the Roo installation directory and symbolic link. This section instead focuses on the removal from your projects.

As mentioned above, a simple way of stopping to use Roo is to simply never load it again. The *_Roo_*.aj files will still be on disk and your project will continue to work regardless of whether the Roo shell is never launched again. You can even uninstall the Roo system from your computer and your project will still work. The advantage of this approach is you haven’t lost most of the benefits of using Roo and it’s very easy to simply reload the Roo shell again in the future. This section covers the more complete removal option should you not even want the *_Roo_*.aj files any more.

Please be aware that enhancement request ROO-222 exists to replace step 1 with a Roo command, and ROO-330 similarly focuses on steps 2 and 3. Please vote for these enhancement requests if you’d like them actioned, although the instructions below still provide a fast and usable removal procedure.

If you decide to change your mind and start using Roo again, the good news is that it’s relatively easy. This is because your project already uses the correct directory layout and has AspectJ etc properly configured. To re-enable Roo, simply open your pom.xml and re-add the org.springframework.roo.annotations <dependency> element. You can obtain the correct syntax by simply making a new directory, changing into that directory, executing roo script vote.roo, and inspecting the resulting pom.xml.

Once you’ve added the dependency, you’re free to load Roo from within your project’s directory and start using the Roo commands again. You’re also free to add @Roo annotations to any .java file that would benefit from them, but remember that Roo is "hands off by default". What that means is if you used the push-in refactor command to move members (e.g. fields, methods, annotations etc) into the .java file, Roo has no way of knowing that they originated from a push-in refactor as opposed to you having written them by hand. Roo therefore won’t delete any members from your .java file or override them in an inter-type declaration.

Our advice is therefore (a) don’t remove Roo in the first place or (b) if you have removed Roo and go back to using Roo again, delete the members from your .java files that Roo is able to automatically manage for you. By deleting the members that Roo can manage for you from the .java files, you’ll gain the maximum benefit of your decision to resume using Roo. If you’re unsure which members Roo can automatically manage, simply comment them out and see if Roo provides them automatically for you. Naturally you’ll need the relevant @Roo annotation(s) in your .java files before Roo will create any members automatically for you.

A final tip if you’d like to return to having ITDs again is that AJDT 2.0 and above offers a Refactor > Push Out command. This may assist you in moving back to ITDs. The Edit > Undo command also generally works if you decide to revert immediately after a Refactor > Push In operation.

Because Spring Roo integrates a large number of other technologies, invariably some people using Roo may experience issues when using certain combinations of technologies together. This section aims to list such known issues in an effort to help you avoid experiencing any problems. If you are able to contribute further information, a solution or workaround to any of these known issues, we’d certainly appreciate hearing from you via the community forums.

Spring Roo observes version number standards based on the Apache Portable Runtime (APR) versioning guidelines as well as the OSGi specifications. In summary this means all Roo releases adopt the format of MAJOR.MINOR.PATCH.TYPE. Each segment is separated by a period without any spaces. The MAJOR.MINOR.PATCH are always integer numbers, and TYPE is an alphanumeric value. For example, Roo 1.0.3.M1 means major version 1, minor version 0, patch number 3 and release type M1.

You can always rely on the natural sort order of the version numbers to arrive at the latest available version. For example, 1.0.4.RELEASE is more recent than 1.0.4.RC2. This is because "RELEASE" sorts alphabetically lower than "RC2". The TYPE segment can generally be broken into two further undelimited portions, being the release type and a numeric increment. For example, RC1 means release candidate 1 and RC4 means release candidate 4. One exception to this is RELEASE means the final general availability of that release. Other common release types include "A" for alpha and "M" for milestone.

We make no guarantees regarding the compatibility of any release that has a TYPE other than "RELEASE". However, for "RELEASE" releases we aim to ensure you can use a given "RELEASE" with any other "RELEASE" which has the same MAJOR.MINOR version number. As such you should be able to switch from 1.0.4.RELEASE to 1.0.9.RELEASE without any changes. However, you might have trouble with 1.0.4.RELEASE to 1.0.9.RC1 as RC1 is a work-in-progress and we may not have identified all regression issues. Obviously this version portability is only our objective, and sometimes we need to make exceptions or may inadvertently overlook an issue. We appreciate you logging a bug report if you identify a version regression that violates the conventions expressed in this section, so that at least we can confirm it and either attempt to remedy it on the next release of that MAJOR.MINOR version range or bring it to people’s attention in the other sections of this appendix.

When upgrading you should review the issue tracker for what has changed since the last version. Because most releases include a large number of issues in the release notes, we attempt to highlight any major issues that may require your attention in the sections below. These notes are not all-encompassing but simply pointers to the main upgrade-related issues that most people should be aware of. They are also written assuming you are maintaining currency with the latest public releases of Spring Roo and therefore the changes you may need to make to your project are cumulative.

Before upgrading any project to the next release of Spring Roo, you should always:

Spring Roo will update your project’s pom.xml versions automatically on your behalf when you load it on an existing project.

If you experience any difficulty with upgrading your projects, please use the community support forum for assistance.

The Spring Roo available today is the result of relatively recent engineering, but the inspiration for the project can be found several years earlier.

The historical motivation for "ROO" can be traced back to 2005. At that time the project’s founder, Ben Alex, was working on several enterprise applications and had noticed he was repeating the same steps time and time again. Back in 2005 it was common to use a traditional layering involving DAOs, services layer and web tier. A good deal of attention was also focused around that time on avoiding anaemic domain objects and instead pursuing Domain Driven Design principles.

Pursuing a rich domain model led to domain objects that reflected proper object oriented principles, such as careful application of encapsulation, immutability and properly defining the role of domain objects within the enterprise application layering. Rich behaviour was added to these entities via AspectJ and Spring Framework's recently-created @Configurable annotation (which enabled dependency injection on entities irrespective of how the entities were instantiated). Naturally the web frameworks of the era didn’t work well with these rich domain objects (due to the lack of accessors, mutators and no-argument constructors), and as such data transfer objects (DTOs) were created. The mapping between DTOs and domain objects was approached with assembly technologies like Dozer. To make all of this work nicely together, a code generator called Real Object Oriented - or "ROO" - was created. The Real Object Oriented name reflected the rich domain object principles that underpinned the productivity tool.

ROO was presented to audiences at the SpringOne Americas 2006 and TSSJS Europe 2007 conferences, plus the Stockholm Spring User Group and Enterprise Java Association of Australia. The audiences were enthusiastic about the highly productive solution, with remarks like "it is the really neatest and newest stuff I’ve seen in this conference" and "if ROO ever becomes an open source project, I’m guessing it will be very polished and well-received". Nonetheless, other priorities (like the existing Spring Security project) prevented the code from becoming release-ready. More than twelve months later Ben was still regularly being asked by people, "whatever happened to the ROO framework?" and as such he set out about resuming the project around August 2008.

By October 2008 a large amount of research and development had been undertaken on the new-and-improved ROO. The original productivity ideas within ROO had been augmented with considerable feedback from real-life use of ROO and the earlier conferences. In particular a number of projects in Australia had used the unreleased ROO technology and these projects provided a great deal of especially useful feedback. It was recognised from this feedback that the original ROO model suffered from two main problems. First, it did not provide a highly usable interface and as such developers required a reasonable amount of training to fully make use of Roo. Second, it imposed a high level of architectural purity on all applications - such as the forced use of DTOs - and many people simply didn’t want such purity. While there were valid engineering reasons to pursue such an architecture, it was the productivity that motivated people to use ROO and they found the added burden of issues like DTO mapping cancelled out some of the gains that ROO provided. A mission statement was drafted that concisely reflected the vision of the project, and this was used to guide the technical design.

In early December 2008 Ben took a completely rewritten ROO with him to SpringOne Americas 2008 and showed it to a number of SpringSource colleagues and community members. The response was overwhelming. Not only had the earlier feedback been addressed, but many new ideas had been incorporated into the Java-only framework. Furthermore, recent improvements to AspectJ and Spring had made the entire solution far more effective and efficient than the earlier ROO model (such as annotation-based component scanning, considerable enhancements to AJDT etc).

Feedback following the December 2008 demonstrations led to considerable focus on bringing the ROO technology to the open source community. The name "ROO" was preserved as a temporary codename, given that we planned to select a final name closer to official release. The "ROO" project was then publicly presented on 27 April 2009 during Rod Johnson’s SpringOne Europe keynote, "The Future of Java Innovation". As part of the keynote the ROO system was used to build a voting application that would allow the community to select a final name for the new project. The "ROO" name was left as an option, although the case was changed to "Roo" to reflect the fact it no longer represented any acronym. The resulting votes were Spring Roo (467), Spring Boost (180), Spring Spark (179), Spring HyperDrive (64) and Spring Dart (62). As such "Spring Roo" became the official, community-selected name for the project.

Roo 1.0.0.A1 was released during the SpringOne Europe 2009 conference, along with initial tooling for SpringSource Tool Suite. The Roo talk at the SpringOne Europe 2009 conference was the most highly attended session and there was enormous enthusiasm for the solution. Roo 1.0.0.A2 was published a few weeks later, followed by several milestones. By SpringOne/2GX North America in October 2009, Roo 1.0.0 had reached Release Candidate 2 stage, and again the Roo session was the most highly attended session of the entire conference. SpringSource also started hosting the highly popular Spring Discovery Days and showing people around the world what they could do with the exciting new Roo tool. Coupled with Twitter, by this stage many members of the Java community had caught a glimpse of Roo and it was starting to appear in a large number of conferences, user group meetings and development projects - all before it had even reached 1.0.0 General Availability!

Spring Roo 1.1.0 was released on 21 October 2010. It was the major architecture refactoring: the transition to an OSGi foundation. Since then Roo ensures Roo’s add-on infrastructure based on a modular, proven, remote dependency-resolvable classpath management model. Modern IDEs such as Eclipse are also built on OSGi, so this approach for tooling modularity and extensibility is well established.

On 24 April 2014 DISID Corporation got the leadership of the Spring Roo project and it continued the goal of providing a code-generation style of RAD tools, focused on helping developers get Java projects done on time.

Spring Roo 1.3.0 was the first version released by DISID Corporation as project lead, released on 20 November 2014, it included complete support for JDK 8 and it was the first time that Spring Roo jar files had been published to Maven Central!

At the time of writing this document, DISID Spring Roo team was busily working towards the 2.0 release. Spring Roo 2.0 will:

Spring Roo’s mission is to "fundamentally and sustainably improve Java developer productivity without compromising engineering integrity or flexibility".

Here’s exactly what we mean by this: