Spring Roo 1.1 Cookbook: Over 60 recipes to help you speed up the development of your Java web applications using the Spring Roo development tool

As you are going to install Spring Roo, you first need to download Spring Roo ZIP archive from the official home page of Spring Roo(http://www.springsource.org/roo/start). Also, ensure that you have the following software installed on your machine:

To install Spring Roo, all you need to do is to follow the given steps:

Spring Roo is built on top of Apache Felix (http://felix.apache.org/site/index.html) OSGi container, which promotes modularity and dynamic assembly of applications. The bundle directory contains OSGi bundles that form part of Spring Roo release. These bundles provide core services required by Roo and add-ons that support code generation. When you first start Spring Roo by executing Roo batch file or shell script, then these bundles are installed and copied into the cache directory of your Spring Roo installation.

Spring Roo comes with certain core services and base add-ons that are part of Spring Roo distribution. Core services like the Roo shell, file system monitor, bootstrap, and so on, provide the necessary infrastructure for the add-ons to perform their intended responsibility. Add-ons are at the heart of Spring Roo and they provide the code generation functionality. For instance, the e-mail add-on adds e-mail support and the JPA (Java Persistence API) add-on helps with setting up a JPA provider, creating JPA entities, their relationships, and so on.

As Roo add-ons are OSGi compliant, you can additionally create a custom add-on or download a third-party add-on and install it as part of your Spring Roo installation to extend Roo's functionality.

To execute the commands defined in this recipe, first create an empty directory from which you will start your Roo shell. For instance, you can create a sub-directory named ch01-recipe inside the cookbook-recipe directory in the C: drive. Go to the ch01-recipe directory and execute roo.bat batch file to start the Roo shell.

To get help and hints from Roo follow the given steps:

As mentioned earlier, Spring Roo consists of core services and add-ons. Add-ons are meant for generating code based on commands executed by the developer. While executing commands like hint and help, Roo is not generating any code. You can say that these commands are processed by the core services and not by any Spring Roo add-on.

Spring Roo also provides with the option to pass arguments to Roo commands, which is covered in the following section. Also when you execute a command from the Roo shell, it is recorded in a Roo script file, which is explained in the Log file for executed Roo commands section.

--<argument-name> <argument-value>

roo> help project

Keyword:                   project
Description:               Creates a new project
 Keyword:                  ** default **
Keyword:                  topLevelPackage
   Help:                   The uppermost package name (this becomes the <groupId> in Maven and also the '~' value when using Roo's shell)
Mandatory:              true
.....

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

Type 'persistence setup' and then hit TAB three times.
.....

roo> hint topics

The following hints are available to help you use Roo:
general, start, jpa, entities, fields, relationships,
controllers, finders, eclipse, logging
Just type 'hint topic_name' (without quotes) to view a specific hint.

The first thing that you need to do is to create an empty directory in which you are going to create your Roo project. Create a ch01-recipe sub-directory in the C:\roo-cookbbook directory, if you haven't created it yet. Start the Roo shell from the ch01-recipe directory by executing the Roo batch file or shell script, as shown here:

C:\roo-cookbook\ch01-recipe>roo

To create a Roo project, execute the project command from your Roo shell, shown as follows:

roo>project --topLevelPackage sample.roo.flightapp --java 6 --projectName flight-app

Created C:\roo-cookbook\ch01-recipe\pom.xml
.....
Created SRC_MAIN_RESOURCES\META-INF\spring\applicationContext.xml
Created SRC_MAIN_RESOURCES\log4j.properties

sample.roo.flightapp roo>

Notice the change in the Roo prompt after the execution of the project command. The change in prompt indicates that you are now working with a project whose top-level package is sample.roo.flightapp. If you start the Roo shell from a directory, which already contains a Roo project, then the Roo prompt will not change.

The following table describes the purpose of each of the arguments passed to the project command:

Spring Roo distribution comes with a Maven add-on , which is responsible for processing the project command. There are more Roo commands that are processed by the Maven add-on, which you will see later in this book.

The output of project command shows that it creates directories with name SRC_MAIN_JAVA, SCR_MAIN_WEBAPP, and so on. These are logical names given to standard directories created by the Maven add-on. The following table shows the directories to which each of these names map in the case of the flight-app project:

As evident from the execution of the project command, not only did it create a maven-ized project, it also created Spring's applicationContext.xml, maven's pom.xml file, and a log4j.properties file. The following XML code shows the contents of the applicationContext.xml file, which contains some interesting details:

<beans ..>

   <context:property-placeholder 
      location="classpath*:META-INF/spring/*.properties"/>

   <context:spring-configured/>

   <context:component-scan base-package="sample.roo.flightapp">
   <context:exclude-filter 
                  expression=".*_Roo_.*" type="regex"/>
   <context:exclude-filter expression=
      "org.springframework.stereotype.Controller"   
      type="annotation"/>
   </context:component-scan>
</beans>

The important inferences that we can derive from the content of applicationContext.xml are:

The other important artifact that was generated during the project creation is the pom.xml file that is used by maven. The following XML code shows how the argument values specified in the project command are used in creating the pom.xml file of the flight-app project:

<project >
   .....
   <groupId>sample.roo.flightapp</groupId>
   <artifactId>flight-app</artifactId>
   <packaging>jar</packaging>
   <version>0.1.0.BUILD-SNAPSHOT</version>
   <name>flight-app</name>
</project>

You may notice that the value of the <packaging> element is jar and not war. The reason for this lies with the fact that we haven't yet added a web layer to the flight-app application. We will see in Chapter 4, Web Application Development with Spring Web MVC and Chapter 5, Web Application Development with GWT, Flex, and Spring Web Flow how we go about creating a web application using Spring Roo.

The pom.xml additionally contains Maven plugins, which are available to Roo projects by default. The following table summarizes some of the important Maven plugins that are available to our newly created flight-app project:

You won't always be starting a project from scratch, and you may find Spring Roo compelling enough (which you will, as we go through its various features) to use in your existing Spring-based Java projects. In such scenarios, you need to do the following:

There are other things you will need to do to convert your existing projects into a Roo project, which we will discuss in relevant recipes.

Start the Roo shell from the C:\roo-cookbook\ch01-recipe directory, which contains the flight-app Roo project.

To import the Roo project into Eclipse or IntelliJ IDEA follow the given steps:

The perform eclipse and perform command commands are processed by the Maven add-on of Spring Roo. The perform eclipse command generates Eclipse IDE specific configuration files, such as .project and .classpath files. Behind the scenes, the perform eclipse command executes the eclipse:eclipse goal of the Maven eclipse plugin.

The perform command is used to execute a Maven command. It accepts a single mandatory argument, mavenCommand , which identifies the Maven goal to execute.

If you are using any IDE other than STS, then ensure that you install AJDT (AspectJ Development Tools), as it gives better development experience when working with projects that make use of AspectJ aspects. For instance, when you open a Java source file in Eclipse IDE (that has AJDT installed), the Cross Reference tab shows the various AspectJ declarations that apply to the selected Java source file, and you can select these declarations to open the corresponding AspectJ ITD files.

Start the Roo shell from the C:\roo-cookbook\ch01-recipe directory, which contains the flight-app Roo project.

Using the logging setup command you can specify the logging level and the package to which it applies, as shown in the following steps:

The logging setup command is processed by the Logging add-on of Spring Roo. The following table describes the arguments that the logging setup command accepts:

As of Spring Roo 1.1.3, using the logging setup command you can't specify a custom package name as the value of the package argument; therefore, you can set a custom package name either by using the properties set command (explained later in this chapter) or by directly editing the log4j.properties file.

Start the Roo shell from C:\roo-cookbook\ch01-recipe directory, which contains the flight-app Roo project.

To view the contents of a properties file, the properties list command requires a path to the properties file and its name. The following properties list command displays the contents of the log4j.properties file:

roo> properties list --name log4j.properties --path SRC_MAIN_RESOURCES

log4j.appender.R = org.apache.log4j.RollingFileAppender
log4j.appender.R.File = application.log
...
log4j.logger.sample.roo.flightapp = DEBUG
log4j.rootLogger = DEBUG, stdout

The Properties file add-on is responsible for processing the properties list command. The following table describes the arguments it accepts:

Start the Roo shell from the C:\roo-cookbook\ch01-recipe directory, which contains the flight-app Roo project.

To manage the properties defined in a properties file follow the given steps:

Like the properties list command, the properties set and properties remove commands are provided by Properties file add-on . The following table describes the arguments that both the properties set and properties remove commands accept:

The properties set command accepts all the arguments that the properties remove command accepts. Additionally, it accepts a mandatory argument, value, which specifies a value of the property being set by the properties set command. If a matching property is found in the properties file, the existing property is updated with the new value. If no matching property is found, a new property is added to the properties file.

You can also change the properties file using your favorite IDE. If you are creating a new Roo project which acts as a template for creating other projects, using properties commands to add, modify, and remove properties from a properties file can be valuable.

If you want to modify logging configuration, you should first consider using the logging setup command (explained earlier in the Configuring logging recipe). If you want to modify database properties, you should use database commands (explained in the Managing database configuration properties recipe in Chapter 2, Persisting Objects Using JPA).

Start the Roo shell from the C:\roo-cookbook\ch01-recipe directory, which contains the flight-app Roo project.

You can create a Java class using the class command, as shown here:

roo> class --class sample.roo.flightapp.service.FlightService --rooAnnotations

Created SRC_MAIN_JAVA\sample\roo\flightapp\service
Created SRC_MAIN_JAVA\sample\roo\flightapp\service\FlightService.java
Created SRC_MAIN_JAVA\sample\roo\flightapp\service\FlightService_Roo_Serializable.aj

~.service.FlightService roo>

When the class command is executed, notice that the Roo prompt changes to refer to the newly created Java class. In the next recipe, titled Adding fields to a Java class, we will see how the changed Roo prompt simplifies performing commands on the referred class. Also, notice that the service directory is automatically created by Spring Roo, if it doesn't exist.

The class command accepts the arguments listed in the following table:

As evident from the list of arguments accepted by the class command, Spring Roo doesn't provide any argument to let you specify the interface(s) that the generated Java class implements. If you want your Java class to implement one or more interfaces, you need to manually modify your class definition.

As the output from class command suggests, apart from FlightService.java, Roo creates a FlightService_Roo_Serializable.aj file—an AspectJ ITD that makes the FlightService class implement java.io.Serializable interface.

The AspectJ ITDs generated by Roo have the following naming convention:

<java-class-name>_Roo_<add-on-name>.aj

Where <java-class-name> is the name of the Java class to which the AspectJ ITD applies.

<add-on-name> is the name of Spring Roo add-on responsible for managing the AspectJ ITD

The *_Roo_*.aj files are managed by Roo and you should not directly modify or delete them.

The following code shows how the FlightService.java file generates the FlightService class using the class command:

package sample.roo.flightapp.service;

import org.springframework.roo.addon.javabean.RooJavaBean;
import org.springframework.roo.addon.tostring.RooToString;
import org.springframework.roo.addon.serializable.RooSerializable;

@RooJavaBean
@RooToString
@RooSerializable
public class FlightService { }

In the given code, Roo annotations were added to the generated FlightService class because we specified the rooAnnotations argument in the class command.

To simplify debugging, developers commonly override the toString method of the java.lang.Object class to output a string containing the value of all the attributes of the class. With Spring Roo, you are relieved of this task because if your class is annotated with @RooToString annotation, Spring Roo takes care of creating and updating the toString method as you add, modify, or remove attributes from your Java class.

When you add an attribute to your FlightService class, Roo creates a FlightService_Roo_ToString.aj—an AspectJ ITD that adds the toString method to the FlightService class, and a FlightService_Roo_JavaBean.aj—an AspectJ ITD that adds getters and setters methods for the attributes defined in the FlightService class. The creation of these aspects is triggered by the presence of @RooToString and @RooJavaBean annotations in the FlightService class.

To see these two ITD files, add the following attribute to FlightService class:

private String origin;

If your Roo shell is running, as soon as you save the FlightService class, Roo will generate a FlightService_Roo_ToString.aj file and a FlightService_Roo_JavaBean.aj file in the same package as the FlightService class. If you observe the Roo shell, you will find that Roo reports that it has created a FlightService_Roo_ToString.aj and FlightService_Roo_JavaBean.aj files, as shown here:

Created SRC_MAIN_JAVA\sample\roo\flightapp\service\
FlightService_Roo_ToString.aj

Created SRC_MAIN_JAVA\sample\roo\flightapp\service\
FlightService_Roo_JavaBean.aj

The following code shows how FlightService_Roo_ToString.aj AspectJ ITD adds the toString method to the FlightService class:

package sample.roo.flightapp.service;

privileged aspect FlightService_Roo_ToString
{
    
    public String FlightService.toString()
   {
      StringBuilder sb = new StringBuilder();
      sb.append("Origin: ")
      .append(getOrigin());
      return sb.toString();
   }
}

The given code shows that FlightService_Roo_ToString is a privileged aspect, that is, it can access even private members of other aspects and classes. The declaration, public String FlightSerivce.toString(), adds a public toString method to the FlightService class that accepts no arguments and returns a String. Everything inside the curly-braces is the implementation of the toString method. Each declaration in an AspectJ ITD file identifies the target of that declaration. In the code, FlightService in the declaration means that the FlightService class is the target; therefore, it will add the toString method to the FlightService class. In the Adding fields to a Java class recipe, we will see how the toString method is automatically updated by Spring Roo when you add more attributes to the FlightService class.

The following figure summarizes how the FlightService_Roo_ToString.aj file in the previous listing declares adding the toString method to the Flight class:

The following code shows the FlightService_Roo_JavaBean.aj AspectJ ITD file:

privileged aspect FlightService_Roo_JavaBean
{
      
  public String FlightService.getOrigin()
   {
      return this.origin;
   }
    
  public void FlightService.setOrigin
   (String origin)
   {
      this.origin = origin;
   }
}

The given code shows that FlightService_Roo_JavaBean.aj is also a privileged aspect and it introduces two methods into the FlightService class: getOrigin and setOrigin, to get and set the value of the origin attribute.

The FlightService_Roo_Serializable.aj AspectJ ITD defines that the FlightService class implements the java.io.Serializable interface, as shown here:

package sample.roo.flightapp.service;

import java.io.Serializable;

privileged aspect FlightService_Roo_Serializable
{
    
   declare parents: FlightService implements Serializable;
    
  private static final long FlightService.serialVersionUID 
   = 5059552858884348572L
}

In the given code, the declare parents: FlightService implements Serializable statement declares that the FlightService class implements the java.io.Serializable interface. The following figure summarizes what this declaration means:

The statement private static final long FlightService.serialVersionUID = 5059552858884348572L, adds a serialVersionUID field (it's the field which you define if your class implements the Serializable interface) to the FlightService class that contains it.

If you want Roo to manage the creation of the toString method and getter and setter methods for attributes of the class, it is recommended that you use the rooAnnotations argument in the class command.

We saw that using the @RooToString annotation creates a method named toString in the corresponding AspectJ ITD file. You can use the toStringMethod attribute of the @RooToString annotation to specify a custom name for the toString method, as shown here:

@RooToString(toStringMethod = "myTostring")
public class MyCustomClass { private String myAttr; }

In the given code, the toStringMethod attribute specifies myToString as the name of the method to act as the toString method for the MyCustomClass. The ITD file corresponding to the @RooToString annotation: MyCustomClass_Roo_ToString.aj will now create a method similar to toString but with the name myToString, as shown here:

privileged aspect MyCustomClass_Roo_ToString
{
   public String MyCustomClass.mytostring ()
   {
      StringBuilder sb = new StringBuilder();
      sb.append("MyAttr: " ).append(getMyAttr());
      return sb.toString();
   }
}

In some cases, you may want to restrict properties from being part of the auto-generated toString method. The @RooToString annotation provides an excludeFields attribute, which lets you specify an array of attributes that should be excluded from the auto-generated toString method, as shown here:

@RooToString(excludeFields={"someAttribute"})
public class MyCustomClass { .. }

In this code, the @RooToString annotation instructs that the toString method of the MyCustomClass class must not include the someAttribute property.

Start the Roo shell from the C:\roo-cookbook\ch01-recipe directory, which contains the flight-app project.

Roo provides field commands, which you can use to add different types of fields in your Java class, shown as follows:

The given output for each of these commands shows that when an attribute is added to the Passenger class for the first time, the Passenger_Roo_JavaBean.aj and Passenger_Roo_ToString.aj files are created. You may notice that every time you add an attribute, the Passenger_Roo_JavaBean.aj and Passenger_Roo_ToString.aj AspectJ ITD files are also updated.

Spring Roo provides multiple field commands for adding different types of attributes to the Java class. For instance, field string is for adding a String type field, field date is for adding a java.util.Date or java.util.Calendar type field, field other is for adding a field of custom Java type, and so on.

The field string, field other, and field number commands accept the name argument, which identifies the name of the attribute to be added to the Java class. The field other and field number also require the type of the attribute.

The following code shows Passenger_Roo_JavaBean.aj AspectJ ITD, which was modified by Spring Roo when we added fields to the Passenger class:

privileged aspect Passenger_Roo_JavaBean
{
   public String Passenger.getFirstName()
   {
      return this.firstName;
   }
   public void Passenger.setFirstName(String firstName)
   {
      this.firstName = firstName;
   }
...
}

The given code shows that Passenger_Roo_JavaBean.aj was updated by Spring Roo to introduce getter and setter methods for each of the fields added to Passenger class. This was possible because of the presence of @RooJavaBean annotation in the Passenger class.

The following code shows Passenger_Roo_ToString.aj AspectJ ITD, which was also modified by Spring Roo when fields were added to the Passenger class:

privileged aspect Passenger_Roo_ToString
{
   public String Passenger.toString()
   {
      StringBuilder sb = new StringBuilder();
      sb.append("FirstName:").append(getFirstName()).append(",");
      sb.append("LastName: ").append(getLastName()).append(", ");
      sb.append("Age: ").append(getAge()).append(", ");
      sb.append("Address: ").append(getAddress());
      return sb.toString();
   }
}

As the given code suggests, it introduces a toString method to the Passenger class, which returns a concatenated String containing the value of each of its attribute. This was possible because the Passenger class was annotated with the @RooToString annotation.

The following figure shows how Spring Roo manages AspectJ ITD files:

The given figure shows that when you start the Spring Roo shell from a directory, it actively monitors the Java classes in the file system that are annotated with Roo annotations (for example @RooToString, @RooJavaBean, and so on). When any of these Java classes are modified using an IDE or any other editor, Spring Roo checks if the AspectJ ITD files (which follow the naming convention *_Roo_*.aj, as explained earlier) corresponding to the Java classes are in sync with the Java classes. If they are not, it updates the AspectJ ITD files accordingly. Spring Roo makes use of add-ons to make modifications to the AspectJ ITD files.

This recipe showed that if you want Roo to automatically generate a toString method and getter and setter methods for all the attributes, then annotate your class with @RooToString and @RooJavaBean annotations.

Spring Roo doesn't provide commands to remove or modify an attribute. So, if you want to remove or modify an existing attribute of a Java class, you can do so using your IDE. Spring Roo will take care of removing or modifying the attribute in corresponding AspectJ ITD files.

Start the Roo shell from the C:\roo-cookbook\ch01-recipe directory, which contains the flight-app Roo project.

Spring Roo provides the interface command to create a Java interface, as shown here:

roo> interface --class sample.roo.flightapp.service.FlightServiceIntf

Created SRC_MAIN_JAVA\sample\roo\flightapp\service\FlightServiceIntf.java

sample.roo.flightapp.service.FlightServiceIntf roo>

The following table describes the arguments that the interface command accepts:

Using Spring Roo you can't add constants or declare methods in your Java interface. To add constants or methods, you need to use your IDE. You may have noticed that the rooAnnotations argument is not available for the interface command; therefore, you can safely assume that Spring Roo doesn't generate any code corresponding to a Java interface when you make modifications to it.

Start the Roo shell from the C:\roo-cookbook\ch01-recipe directory, which contains the flight-app Roo project.

Spring Roo provides a focus command, which lets you change the target of your commands to a different Java type. The following sequence of steps shows how we can use the focus command to switch from one type to another:

The class argument of the focus command lets you specify the fully-qualified name of the Java type with which you want to work. The ~ symbol is used to indicate the top-level package of the Roo project that you specified during creation of the Roo project.

The use of the focus command is mainly to simplify writing commands targeting a particular Java type. If you don't want to use the focus command in a situation, then you can always use the class argument of the command to specify the target Java type of the command.

If your Roo shell is still open, then exit it and remove all the files from the C:\roo-cookbook\ch01-recipe directory. Download the ch01.roo file from the book's website and copy it to C:\roo-cookbook\ch01-recipe. Start the Roo shell from the C:\roo-cookbook\ch01-recipe directory.

To create the application skeleton execute the script command, by specifying the file containing Roo commands, as shown here:

roo>script --file ch01.roo --lineNumbers

The script command accepts the following arguments:

One of the features that you will not find in Spring Roo is to revert the execution of a previous command. For instance, if you added a field using the field command and now you want to rollback the changes it made, then it is not possible. If you have mistakenly executed a Roo command, you can remove it from the log.roo file and re-execute the commands in log.roo using the script command.

If a Roo command fails for some reason, it is commented out in the log.roo file. So, you don't need to worry about removing commands that failed execution from your log.roo file.