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.
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.
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.
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:
To get help from Spring Roo, all you need to do is enter the
helpcommand 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
hand 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
hint. Now, enter
heinto 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
Once you enter the
helpcommand, 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
helpcommand provides a short description about all the commands supported by Spring Roo. For instance, it tells you that you can use the
quitcommand to exit the Roo shell and the
versioncommand to know the version of Spring Roo that you are currently using.
Now that you know how
helpcommand is useful, let's try out the
hintcommand, 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
projectcommand. We will make use of the
hintcommand in later recipes to discover how it is useful in creating a fully functional project.
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
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.
Like most Roo commands, the
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
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
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:
To simplify using the
help commands, Roo lets you specify arguments without un-necessary frills. For instance, you can enter the
project command to get help information on the
project command or you can enter the
jpa command to get hints related to JPA.
The following output from the Roo shell shows the results from executing the
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
project command suggests that the
project command accepts a mandatory argument named
jpa command provides high-level details about the
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
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:
relationships, and so on.
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.
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.