Getting started with Roo shell

Prerequisites

Before you start working with Roo, make sure you have following installed:

1. Java V6 JDK
2. Apache Maven V2.0.9 or above

Installing Spring Roo

To install stand-alone Spring Roo:

1. You can download Roo stand-alone command-line shell or use the built-in Roo SpringSource Tool Suite (STS) plug-in. I would suggest downloading both and using them together because STS offers many additional features over Eclipse for Spring-based applications.
   1. Spring Roo
   2. SpringSource Tool Suite
2. Unzip Spring Roo to the location of your choice.
3. Set the environment variable:
   1. On a Windows machine, add %ROO_HOME% /bin to the path where ROO_HOME is the path to the unzipped Roo files.
   2. On a *nix machine, create a symbolic link to $ROO_HOME/bin/roo.sh
      (e.g., sudo ln -s ~/spring-roo-1.x.x/bin/roo.sh /usr/bin/roo)

Building an application

To show you the power of Roo, let's create a simple enterprise conference application. A conference application has two entities: Speaker and Talk. A Speaker can give one or more talks, and Talk will be given by only one speaker. The simple class diagram is shown in Figure 1.

Figure 1. Class Diagram Speaker Talk

Create the application:

1. Open your operating system command-line shell.
2. Create a directory named conference using the mkdir command.
3. Go to the conference directory in your shell.
4. Type roo. This command will initiate the Roo shell as shown in Listing 1.

Listing 1. Starting the Roo shell

C:\Users\xebia\demo\conference>roo ____ ____ ____ / __ \/ __ \/ __ \ / /_/ / / / / / / / / _, _/ /_/ / /_/ / /_/ |_|\____/\____/ 1.1.B.RELEASE [rev 793f2b0] Welcome to Spring Roo. For assistance press TAB or type "hint" then hit ENTER. roo>

Now that we are inside the Roo shell, we will use Roo's hint command to guide us through the next steps. hint suggests creating a new Maven-based Spring project using project (see Listing 2).

Listing 2. Using hint in the Roo shell

Welcome to Spring Roo. For assistance press TAB or type "hint" then hit ENTER. roo> hint Welcome to Roo! We hope you enjoy your stay! Before you can use many features of Roo, you need to start a new project. To do this, type ’project’ (without the quotes) and then hit TAB. Enter a --topLevelPackage like ’com.mycompany.projectname’ (no quotes). When you're finished completing your --topLevelPackage, press ENTER. Your new project will then be created in the current working directory. Note that Roo frequently allows the use of TAB, so press TAB regularly. Once your project is created, type ’hint’ and ENTER for the next suggestion. You're also welcome to visit http://forum.springframework.org`for Roo help. roo>

As suggested by the hint command, we will create a project using the project command. This command has one required attribute, topLevelPackage, to specify the name of the root package. In addition to the required attribute, we will use two optional attributes: java (to specify the Java version) and projectName (to specify the name of the project). Type the following:

project --topLevelPackage com.dw.roo.conference --java 6 --projectName conference

This command will create a Maven V2-managed Spring-based project as shown in the following output:

Created C:\Users\xebia\demo\conference\pom.xml Created SRC_MAIN_JAVA Created SRC_MAIN_RESOURCES Created SRC_TEST_JAVA Created SRC_TEST_RESOURCES Created SRC_MAIN_WEBAPP Created SRC_MAIN_RESOURCES\META-INF\spring Created SRC_MAIN_RESOURCES\META-INF\spring\applicationContext.xml Created SRC_MAIN_RESOURCES\log4j.properties

Again, type hint to ask Roo for the next action. This time it suggests setting up the persistence mechanism. Type persistence setup on the shell and press Tab three times. You will obtain options for --provider. Press H and then Tab to complete "HIBERNATE". After the provider, press tab for database choices, and you will see a number of options. Because we are using Hibernate as our provider, we cannot choose a non-relational database like Google App Engine. For now, we are going to use the HYPERSONIC_IN_MEMORY database.

persistence setup --provider HIBERNATE --database HYPERSONIC_IN_MEMORY

There are other optional attributes, such as username and password, which we don't need at this time.

Now that we have set up the persistence mechanism, we will again utilize the hint command. This time we're told to create entities using the entity command. Entity is used to create the actual domain objects and has one required attribute, class, to specify the name of the entity. In addition to the required --class attribute, we will use the --testAutomatically attribute, which creates integration tests for a domain object. Let's create two entities: Speaker and Talk.

entity --class ~.domain.Speaker –testAutomatically entity --class ~.domain.Talk --testAutomatically

I have used ~ as a placeholder for project top-level package.

Entity will create a flexible, feature-rich JPA entity. The created entities will have JPA @Entity with ID, version, EntityManager, and a no-argument constructor. The generated entity will have methods such as persist, merge, remove, flush, count, find, and findById, etc. If you look at the output of this command, you will notice that this command, in addition to creating Java files (for Speaker and Talk), also created AspectJ files ending with *Roo_*.aj. These *Roo_*.aj are called Intertype Declaration (ITD), Mixins, or Introductions. Roo uses ITD as a code-generation artifact. ITDs allows Roo to generate code in a separate compilation unit, but ITDs are combined into the same compiled class at compilation time. AspectJ intertype declarations are used to automatically generate ID and version fields, and getters and setters for persistence fields in domain classes.

Using hint again provides the suggestion to add fields to the entity using the field command. Let's add some fields to the Speaker entity:

field string --fieldName firstname --class ~.domain.Speaker --notNull field string --fieldName lastname --notNull field string --fieldName email --unique --notNull field string --fieldName organization field date --fieldName birthdate --type java.util.Date --past --notNull field number --type java.lang.Long --fieldName age --min 25 --max 60

--class options let us specify which class we want to add fields to.

The field command can be used to specify JavaBean validation-specific annotations with options such as --max and --min, etc. It can also be used to specify JPA-specific annotations with options like --fetch, --column, and --unique, etc. For date fields, you can also specify whether the date should be past or future as used above. Using field, you don't have to remember these annotations.

Now let's add some fields to the Talk entity:

field string --fieldName title --class ~.domain.Talk --notNull field string --fieldName description --notNull --sizeMax 4000

So far, we have created the entities and added fields to them, but we have not specified the relationship between them. The relationship between Speaker and Talk is ONE_TO_MANY (i.e., one speaker can give any number of talks). This is done usingfield, as shown below:

field set --fieldName talks --type ~.domain.Talk --class \ ~.domain.Speaker --cardinality ONE_TO_MANY field reference --fieldName speaker --type ~.domain.Speaker \ --class ~.domain.Talk –-notNull

Now we will want to scaffold a web tier for conference application. This is done using the controller command. The most convenient way to generate controllers and all relevant web artifacts is to use controller all.

controller all --package ~.web

The first use of the controller command will also add additional dependencies, such as Spring MVC and Tiles to your project. This might take some time to run as it has to download all the dependencies (if they don't exist in your Maven repository). This command also shows one of the features of Roo: that it adds dependencies only when they are needed.

Next, we will set up the log4j using logging command:

logging setup --level INFO --package ALL_SPRING

The last thing we should do before quitting the Roo shell is run the integration tests that were generated when we specified --testAutomatically with the entity command. To run the tests from within the shell, type perform tests.

Roo delegates the call to Maven to run the tests, so therefore, perform tests is equivalent to a mvn test command. Quit the shell by typing q or quit.

These commands will create a fully functional conference application. Next we will run this application.

To run the application, type mvn tomcat:run which will start the jetty server. Open a web browser and go tohttp://localhost:8080/conference/. You will see the screen shown in Figure 2.

Figure 2. Conference application home page
 

You can click Create new Speaker to create a conference speaker. You can also view, edit, and delete a user by clicking List all Speakers. In the same way, you can create a Talk, but not before a Speaker is created.

This is a simple application, but it shows how easily you can create a new Spring-based web application from scratch in minutes. In the second part of this series, I will show you how to build an application using different Roo features and add-ons.

Now that we have created a simple application, I will show how you can build the Spring Roo source on Windows and Ubuntu.

Posted in: Spring,Spring Roo