Creating a Roo project

This is the first recipe in which you will see Spring Roo doing some real work to help you create a Java enterprise application. This recipe shows how to go about creating a Roo project using project command. The end result of following this recipe will be a project, which follows standard Maven directory structure. The project created in this recipe can be packaged as a JAR file because it doesn't have a web layer. In Chapter 4, Web Application Development with Spring Web MVC and Chapter 5, Web Application Development with GWT, Flex, and Spring Web Flow you will see how to create a web layer of an enterprise application using Spring Roo. The project that you will create in this recipe will act as a foundation for the rest of the recipes in this chapter.

Getting ready

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

How to do it...

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.

How it works...

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

Argument	Purpose
topLevelPackage	This is a Mandatory argument, which identifies the base or root package of your project. You will refer to this package frequently in your Roo commands using the tilde symbol (~). The value of this argument becomes the value of the <group-id> element in maven's pom.xml file.
java	This is an optional argument, which specifies the version of Java (must be 5, 6, or 7) with which the source and compiled classes of the Roo project should be compatible with. If unspecified, the Java version is auto-detected by Spring Roo.
projectName	This is an optional argument, which specifies the name of the project. The value of this argument becomes the value of <artifact-id> and <name> elements in maven's pom.xml file. If unspecified, the last part of the package name specified as the value of topLevelPackage argument is used. For instance, if the topLevelPackage argument value is sample.roo.flightapp, and the projectName argument is not specified, the value of projectName argument is assumed to be flightapp.

Tip

Use TAB or CTRL + SPACE regularly for discovering mandatory and optional attributes, and their pre-defined values

As it's hard to remember all the mandatory and optional attributes of different Roo commands, it's recommended that you use TAB (if you are using standalone Roo) or CTRL + SPACE (if you are using Roo from within Eclipse or STS) to use the auto-completion feature of Roo. Roo not only provides auto-completion of Roo commands (as we saw in an earlier recipe), but it also displays the mandatory arguments of a command when you press TAB or CTRL + SPACE. If you want to know about the optional arguments of a command, simply enter -- followed by TAB or CTRL + SPACE. To restrict users from entering any arbitrary value, a command argument may accept only a particular value from a set of pre-defined values for that argument. The pre-defined values are defined by the add-on responsible for processing the command. If an argument accepts a value from a set of pre-defined values by Roo, it is displayed when you press TAB or CTRL + SPACE.

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:

Path value	Project directory
SRC_MAIN_JAVA	Refers to the root of the Java source directory, which contains application's Java sources: ch01-recipe\src\main\java.
SRC_MAIN_RESOURCES	The root of the directory, which contains resources (Spring's application context XML, database properties file, log4j properties file, persistence.xml file, and so on) required by the Java enterprise application: ch01-recipe\src\main\resources.
SRC_TEST_JAVA	The root of the Java source directory, which contains unit and integration tests: ch01-recipe\src\test\java.
SRC_TEST_RESOURCES	The root of the directory, which contains resources required during unit and integration testing: ch01-recipe\src\test\resources.
SRC_MAIN_WEBAPP	The web application directory, which contains web pages, images, style sheets, and web application configuration: ch01-recipe\src\main\webapp.
ROOT	Refers to the root directory of the project, which is ch01-recipe in case of flight-app project.
SPRING_CONFIG_ROOT	Refers to the directory, which contains Spring's application context XML file. In the context of flight-app project this refers to ch01-recipe\src\main\resources\META-INF\spring.

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 definition of the <property-placeholder> element of Spring's context namespace indicates that you must put your properties files that contain configuration information for Spring beans, in the META-INF/spring directory so that they can be picked up by Spring's application context. In the next chapter, we will see how this is used by Roo-generated applications to read database properties from an external properties file.

• The <spring-configured> element of Spring's context namespace specifies that objects that are annotated with @Configurable annotation are configured using Spring, even if they are created outside of the Spring container. The objects created outside the Spring container include objects that are created programmatically using the new operator or by reflection. We will see example usage of @Configurable annotation in Chapter 2, Persisting Objects Using JPA.

• The <component-scan> element of Spring's context namespace specifies that Spring components (that is, components annotated with @Service, @Repository and @Component Spring annotations) found inside the sample.roo.flightapp package or its sub-packages are automatically registered with Spring's application context. Later in this chapter, we will use this feature to create a service class in the flight-app project, which is auto-registered with Spring's application context.

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:

Maven Plugin	Usage
IDEA plugin	You may use this plugin to convert the flight-app project into an IntelliJ IDEA project.
Eclipse plugin	You may use this plugin to convert the flight-app project into an Eclipse project.
AspectJ compiler plugin	This plugin weaves AspectJ aspects into your project classes. This plugin is used internally by Spring Roo. We will see the AspectJ compiler in action in Chapter 2.
Tomcat and Jetty plugins	You can use these plugins during development to run Tomcat or Jetty in embedded mode to test your web application.

There's more...

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:

1. Convert your existing Spring-based project into a standard Maven project as created by Spring Roo's project command.

2. Add the AspectJ compiler plugin to the pom.xml file of your project.

3. Move bean definitions in your existing project to the applicationContext.xml file in META-INF/spring directory.

4. Move the properties file used for configuring Spring beans to META-INF/spring/ directory.

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.

See also

• The Configuring logging recipe discusses how to configure logging in Roo projects

• Refer to the Creating a Java class and Create a Java interface recipes to find out how you can use Spring Roo to create classes/interfaces in your application