Getting help and hints from Roo

One of the key features of the Spring Roo shell is that it provides context-sensitive hints to the developers. The hints feature of Spring Roo provides step-by-step guidance on developing a working enterprise application in minutes. For instance, if you haven't created a Roo project in the directory from which you are running the Roo shell, issuing the hint command tells you how to go about creating a Roo project. If Roo finds that the directory from which the Roo shell is executing contains a Roo project but a JPA persistence provider is not set up yet, it suggests you set up a persistence provider (such as OpenJPA and Hibernate) for your project.

Tip

What is a Roo project?

A Roo project is nothing but a Java project whose source code consists of Java source files and .aj (AspectJ) files. If you decide to move away from Roo, you can easily do so because there is no runtime dependency of the generated code on any Roo libraries. Refer to the Removing Roo-specific details from your project recipe in Chapter 7 to see how to use IDEs like Eclipse and STS to remove Roo.

The help command provides a list of commands that are supported by a particular version of Spring Roo, accompanied with a short description of the purpose of the command. The commands listed by the help command are the only commands that you can execute from the Roo shell.

It is important to note that you may not be able to execute some of the Roo commands listed by help command, if they are not applicable to your Roo project. For instance, if you haven't set up a JPA persistence provider for your enterprise application, the Roo shell doesn't allow you to execute commands for creating JPA entities.

Getting ready

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.

How to do it...

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

1. To get help from Spring Roo, all you need to do is enter the help command in your Roo shell. But, we will do it a bit differently in our case. Instead of entering the complete command name, enter the letter h and press TAB (if you are using standalone Spring Roo installation) or CTRL + SPACE if you are using Spring Roo installed in Eclipse IDE or STS. You will get the following output from the Roo shell:

   roo> h
   help   hint
   roo> h
   

   As shown in the given code, the Roo shell provides the list of matching commands that it finds. In this case, it's help and hint. Now, enter he into the Roo shell and press TAB or CTRL + SPACE. You will notice that now the Roo shell automatically completes the command for you to reflect the matching help command.

   Once you enter the help command, you will get the list of commands supported by Spring Roo, shown as follows:

   roo> help
   .....
   * class - Creates a new Java class source file in any project path
   * interface - Creates a new Java interface source file in any project path
   * project - Creates a new project
   * quit - Exits the shell
   * version - Displays shell version
   .....
   

   As you can see, the help command provides a short description about all the commands supported by Spring Roo. For instance, it tells you that you can use the quit command to exit the Roo shell and the version command to know the version of Spring Roo that you are currently using.

2. Now that you know how help command is useful, let's try out the hint command, shown as follows:

   roo> hint
   Welcome to Roo! We hope you enjoy your stay!
   Before you can use many features of Roo, you need to start a new project.
   To do this, type 'project' (without the quotes) and then hit TAB.
   Enter a --topLevelPackage like 'com.mycompany.projectname' (no quotes).
   When you've finished completing your --topLevelPackage, press ENTER.
   Your new project will then be created in the current working directory.
   ....
   

   As you can see from the given output, Spring Roo shows the hint on how to go about creating a project using the project command. We will make use of the hint command in later recipes to discover how it is useful in creating a fully functional project.

How it works...

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.

There's more...

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.

Passing arguments to Roo commands

Like most Roo commands, the help and hint commands accept arguments. Arguments are additional parameters that are passed to a Roo command to customize command behaviour. For instance, the help command accepts a command argument and the hint command accepts a topic argument.

Earlier, we saw that the help command provides high-level details about commands supported by Spring Roo. The command argument is used to specify the name of the command for which detailed help information is needed, including information about required and optional arguments that can be passed to the Roo command. Similarly, the topic argument of hint command provides detailed information on a particular topic. The command and hint arguments are optional arguments; Roo shell doesn't force you to specify them.

In most cases Roo expects you to specify arguments in the following format:

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

To simplify using the hint and help commands, Roo lets you specify arguments without un-necessary frills. For instance, you can enter the help project command to get help information on the project command or you can enter the hint jpa command to get hints related to JPA.

The following output from the Roo shell shows the results from executing the help project and hint jpa commands:

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.
.....

As you can see from the given output, the help command gives the exact details about a command. For instance, the help project command suggests that the project command accepts a mandatory argument named topLevelPackage. The hint jpa command provides high-level details about the jpa topic.

So, the question arises, how do you find the topics on which hints are available? Well, you can find these topics from Roo by executing the hint topics command, shown as follows:

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 given output suggests that Spring Roo provides hints on the following topics: jpa, entities, fields, relationships, and so on.

The help and hint commands are the most often used commands; it is recommended that you should use them as and when required while working with your Roo project.

Log file for executed Roo commands

Let's say that you created an enterprise application using Spring Roo consisting of Spring Web MVC and Hibernate frameworks. Additionally, you executed Roo commands to add e-mail and JMS message sending support to some of the classes that you created as part of your enterprise application. Now, let's say a similar project needs to be created in your organization, which makes use of Spring Web MVC, Hibernate frameworks, and requires e-mail and JMS message sending functionalities. You can either re-execute all the Roo commands (that you used in your earlier enterprise application) to create the new enterprise application, or you can simply execute the Roo script from the earlier enterprise application.

When you execute a command from the Roo shell, it is recorded in a Roo script file, named log.roo. You will notice that a log.roo script file is created in the ch01-recipe directory. The log.roo script contains the commands that you executed using the Roo shell and also the details of when you started the Roo shell or exited it. This feature of Spring Roo can be useful if you want to review the commands that you executed or if you want to execute the same set of commands using the script command of Spring Roo. In a moment you will see how to execute a Roo script file, in the Creating application artifacts from Roo script recipe of this chapter.

See also

• The next recipe, Creating a Roo project shows how you can use the help command to discover the details of the project command, which is used for creating a Roo project.