Like other rapid development platforms, Roo has a number of add-ons available for installation over the internet, because its development team hosts a live directory of components that automatically downloads on startup. You may see the download pro
cess occurring on the top right of your console window, finishing with
Downloaded 100% of roobot.xml.zip
The downloaded file contains a list of all Roo add-ons registered with Roo-bot, a service available to Roo developers that exposes published add-ons to all Roo users. We’ll experiment with this directory, and we’ll start by learning how to search for add-ons;
then we’ll install and test an add-on; and, finally, we’ll remove an add-on.
The key thing to remember is that, unlike Grails or Rails, where the add-on is used at runtime, our add-ons are merely Roo shell extensions. After we compile the project code, all effects of the add-on will result in standard Java EE code and web artifacts.
269 Working with published Roo add-ons
11.3.1 Finding the Roo repository add-ons
Let’s get started. Use the addon list command to show a list of add-ons in the reposi
tory, which we have excerpted in the following example:
roo> addon list
65 found, sorted by rank; T = trusted developer; R = Roo 1.2 compatible ID T R DESCRIPTION ---
01 Y Y 3.0.5.RELEASE
02 - Y 1.0.0.0001 This bundle wraps the standard Maven artifact:
google-collections-1.0.0.
...
08 - Y 0.7.0 JasperReport support for Spring MVC based projects. With JasperReport support you give to the project the feature of create...
...
42 Y Y 1.2.0.M1 Offers GIT integration in the project. Each
successfully executed command will be automatically committed to a local GIT...
...
57 - - 1.0.0 The Executable WAR Addon configures the Maven project to makes it possible to create web applications that can be run from the command
...
You’ll get a full list of the add-ons in the repository, whether or not they are compati
ble with your version of Roo. The fields returned are
ID—The search result # of the add-on.
(T)rusted—Whether the team member deploying the add-on is a trusted or approved Roo developer. These add-ons must be approved by the Roo team to gain the T code.
(R)oo 1.2 Compatible—These add-ons are compatible with the add-on system as of version 1.2 or later.
Description—The description of each add-on. It starts with the version of the add-on.
The addon list command has several options, including
--compatibleOnly—Show only compatible add-ons.
--trustedOnly—Show only add-ons by trusted developers.
--communityOnly—Show only add-ons contributed to the system by the outside community. Some of the add-ons available include upgrades of key Roo compo
nents and optional JARs, so this option weeds out internal JARs from the list.
--linesPerResult—By default, Roo shows only two comment lines. If an add- on has more documentation, you can expand the number of rows to read the result.
--refresh—The list of add-ons are loaded on startup. Use this option to force a reload of the list.
You can also use the search command to locate a specific add-on. The --requires- Description option searches text within the description:
roo> addon search --requiresDescription git
1 found, sorted by rank; T = trusted developer; R = Roo 1.2 compatible ID T R DESCRIPTION ---
01 Y Y 1.2.0.M1 Offers GIT integration in the project. Each
successfully executed command will be automatically committed to a local GIT...
The --requiresCommand option searches for the commands provided by the add-on:
roo> addon search --requiresCommand git
1 found, sorted by rank; T = trusted developer; R = Roo 1.2 compatible ID T R DESCRIPTION ---
01 Y Y 1.2.0.M1 Offers GIT integration in the project. Each
successfully executed command will be automatically committed to a local GIT...
For all of the add-on commands, you can type two dashes (--) and use the [TAB] com
pletion key to see additional options.
More than one way to install a Roo add-on
There are four ways to install an add-on to your Roo configuration:
Use the addon install command to install it from the central Roo add-on repository.
Use the osgi start command to install add-ons from a URL or a file. You’ll use this technique later in this chapter when you write your own add-ons.
Use the osgi obr repository commands to mount an OSGi repository and install the add-on from that repository. Useful in a corporate environment where your team needs to share company-wide add-ons.
Copy the add-on JAR file to the Roo installation’s bundles directory.
We discuss the osgi start and osgi obr commands in the next chapter.
The report format is a bit basic, but we hope to soon see an add-on portal website that displays this information in a more useful way.
The addon info command shows details about your add-on. The following example assumes roo-equals-roo-addon was search result 01:
Name...: Spring Roo - Addon - GIT
BSN...: org.springframework.roo.addon.git
Version...: 1.2.0.M1 [available versions: 1.1.1.RELEASE, 1.1.2.RELEASE, 1.1.3.RELEASE, 1.1.4.RELEASE, 1.1.5.RELEASE, 1.2.0.M1]
Roo Version..: 1.2 Ranking...: 0.0
JAR Size...: 14278 bytes
PGP Signature: 0xEC67B395 signed by Alan Stewart (stewarta@vmware.com)
271 Working with published Roo add-ons
OBR URL...: http://spring-roo-repository.springsource.org/repository .xml.zip
JAR URL...: httppgp://spring-roo-repository.springsource.org/release /org/springframework/roo/org.springframework.roo.addon.g it/1.2.0.M1/org.springframework.roo.addon.git-1.2.0.M1.j
ar
Commands...: 'git revert commit' [Roll project back to a specific com mit]
Commands...: 'git revert last' [Revert last commit]
Commands...: 'git log' [Commit log]
Commands...: 'git push' [Roll project back to a specific commit]
Commands...: 'git setup' [Setup Git revision control]
Commands...: 'git commit all' [Trigger a commit manually for the proj ect]
Commands...: 'git config' [Git revision control configuration (.git/c onfig)]
Commands...: 'git reset' [Reset (hard) last (x) commit(s)]
Description..: Offers GIT integration in the project. Each successfully executed command will be automatically committed to a lo cal GIT repository. Tags: #git, #scm, #wrappedCoreDepend
ency
The Roo add-on system is a great way to find and experiment with published and con- tributed add-ons. You can also install your own add-on to this repository, further con- tributing to the Roo platform. We’ll show you how in chapter 12.
11.3.2 Installing with add-on install
Now that you’ve learned how to search for add-ons, it’s time to install one and exper- iment. Let’s install the Roo Git add-on. There are two ways to do this.
The first is to use the search ID of a previously executed search:
roo> addon search --requiresCommand git
1 found, sorted by rank; T = trusted developer; R = Roo 1.2 compatible ID T R DESCRIPTION ---
01 Y Y 1.2.0.M1 Offers GIT integration in the project. Each
successfully executed command will be automatically committed to a local GIT...
roo> addon install id --searchResultId 01
The second is to use the bundle symbolic name, abbreviated as BSN in the previous addon info command:
roo> addon install bundle --bundleSymbolicName ➥
org.springframework.roo.addon.git
This method works well when you’re putting together Roo script files for your developers to use in the future, and don’t want to rely on a search result ID.
WATCH THOSE SEARCH IDS Each time you perform an addon search or addon list command, the search result IDs change. They aren’t permanent num- bers.
It's time to use your add-on to set up a git repository.
11.3.3 Using the Git add-on
You can check your shell to see the new command by hitting [TAB]:
roo> [TAB]
*/ /* // ; addon
backup class controller date dependency development download email enum equals
exit field flash focus git
gwt help hint interface jms
json logging metadata osgi perform
persistence pgp poll process properties proxy quit reference script system
test version web
Now the git command appears alongside the rest of the Roo shell commands.
You can set up a Git repository from a Roo project. This add-on provides a series of shell commands that configure and automatically manage changes to the reposi
tory with each shell command. To set up the Git repository, you can issue this one- line command:
roo> git setup
Git commit 4c655f6c43eb4e76e1cfa13919f213ca3466a5a7 [git setup]
This command will issue a git init command in your project directory, if needed, and otherwise use your existing Git configuration. It will then issue a git commit to record the change you’ve made.
Now, any change you make to your project configuration in the Roo shell will be followed by a commit to the Git repository:
roo> entity jpa --class ~.model.StudentSurvey --testAutomatically Created SRC_MAIN_JAVA/.../model/StudentSurvey.java
Created SRC_TEST_JAVA/.../model/StudentSurveyDataOnDemand.java Created SRC_TEST_JAVA/.../model/StudentSurveyIntegrationTest.java Created SRC_MAIN_JAVA/.../model/StudentSurvey_Roo_Configurable.aj Created SRC_MAIN_JAVA/.../model/StudentSurvey_Roo_ToString.aj Created SRC_MAIN_JAVA/.../model/StudentSurvey_Roo_Jpa_Entity.aj Created SRC_MAIN_JAVA/.../model/StudentSurvey_Roo_Jpa_ActiveRecord.aj Created SRC_TEST_JAVA/.../model/StudentSurveyIntegrationTest_Roo_Config
urable.aj
Created SRC_TEST_JAVA/.../model/StudentSurveyDataOnDemand_Roo_DataOnDem and.aj
Created SRC_TEST_JAVA/.../model/StudentSurveyIntegrationTest_Roo_Integr ationTest.aj
Created SRC_TEST_JAVA/.../model/StudentSurveyDataOnDemand_Roo_Configura ble.aj
Git commit 87f7126c44029e99ed9345d8884cde47d43d545c
[entity jpa --class ~.model.StudentSurvey --testAutomatically]
Pretty handy. You can also force a commit right from the shell:
roo> git commit all --message "configured the big one"
And you can also revert to your last commit:
---
273 Working with published Roo add-ons
git revert last --message "undid the entity create - not needed."
Revert of commit HEAD~0 successful.
Finally, you can also review your Git log:
~.model.StudentSurvey roo> git log --- Start Git log ---
commit id: dc95fbfcb94c528ec7846e95fe4b34b0157f66ca message: Revert "entity jpa --class ~.model.StudentSurvey --testAutomatically"
This reverts commit 87f7126c44029e99ed9345d8884cde47d43d545c commit id: 87f7126c44029e99ed9345d8884cde47d43d545c
message: entity jpa --class ~.model.StudentSurvey --testAutomatically
commit id: 4c655f6c43eb4e76e1cfa13919f213ca3466a5a7 message: git setup
There are more features of this add-on, so consult your addon info output and experiment.
11.3.4 Upgrading Roo add-ons
You can use the addon upgrade command to search for and automatically install upgrades to Roo add-ons:
roo> addon upgrade available
The following add-ons / components are available for ➥
upgrade for level: ANY
[level: ANY] ...roo.addon.property.editor;1.1.4.RELEASE > ➥
1.2.0.BUILD-SNAPSHOT
[level: ANY] ..roo.addon.gwt;1.1.4.RELEASE > 1.2.0.BUILD-SNAPSHOT [level: ANY] ..roo.addon.propfiles;1.1.4.RELEASE > 1.2.0.BUILD-SN..
[level: ANY] ..roo.addon.web.selenium;1.1.4.RELEASE > ➥
1.2.0.BUILD-SNAPSHOT
[level: ANY] ..roo.addon.solr;1.1.4.RELEASE > 1.2.0.BUILD-SNAPSHOT [level: ANY] ..roo.addon.json;1.1.4.RELEASE > 1.2.0.BUILD-SNAPSHOT [level: ANY] ..roo.addon.backup;1.1.4.RELEASE > 1.2.0.BUILD-SNAPSHOT ...
BEWARE OF UPDATING THE INTERNAL ROO ADD-ONS In the previous example, the add-ons from Roo 1.1.4 are upgradable to a build snapshot version of Roo 1.2.0. Due to a missing add-on, however, when we upgraded to 1.2.0, the Roo shell detected a problem and was no longer functional. If you accidentally upgrade your Roo artifacts and the shell won’t start properly, you can go back to the original installed version by deleting the contents of the cache direc
tory in your Roo installation directory.
You’ll also lose any additional add-ons you’ve installed previously, so it’s a good idea to store your third-party add-on installation scripts in your version control system and update them whenever you add a new approved add-on.
By default, the upgrade engine searches for any version, including releases, release candidates, and milestone releases. You can customize this, for example, by limiting to only release-level add-ons:
roo> addon upgrade settings --addonStabilityLevel RELEASE Add-on Stability Level: RELEASE stored
Or you can list only available add-ons for your Roo shell release level:
roo> addon upgrade available
No add-ons / components are available for upgrade for level: RELEASE
This setting is stored between restarts, so if you want to experiment, make sure to reset it before searching for upgrades.
11.3.5 Trusting PGP keys
When a user installs add-ons using the addon command, Roo verifies whether or not the user trusts the add-on developer by checking whether they have trusted the devel
oper’s PGP key.
You can see the following list of trusted keys that are installed into your Roo envi
ronment by issuing the pgp key command:
roo> pgp list trusted keys
>>>> KEY ID: 0xBB0371CE <<<<
More Info: http://keyserver.ubuntu.com/pks/lookup? ➥
fingerprint=on&op=index&search=0xBB0371CE Created: 2010-Jul-11 17:29:06 +0000
Fingerprint: eb25ea09869e3be5def83c43a9cb702ebb0371ce Algorithm: RSA_GENERAL
User ID: Spring Roo <s2-roo@vmware.com>
Signed By: Key 0x00B5050F (Ben Alex <balex@vmware.com>) Signed By: Key 0xBB0371CE (Spring Roo <s2-roo@vmware.com>) Subkey ID: 0x90BDE537 [RSA_GENERAL]
>>>> KEY ID: 0x6163CB9E <<<<
More Info: http://keyserver.ubuntu.com/pks/lookup? ➥
fingerprint=on&op=index&search=0x6163CB9E Created: 2010-Jun-09 06:07:56 +0000
Fingerprint: 868df24600c3c8e4d999ea3584f200286163cb9e Algorithm: RSA_GENERAL
User ID: Stefan Schmidt <schmidts@vmware.com>
Signed By: Key 0x00B5050F (Ben Alex <balex@vmware.com>) Signed By: Key 0xEC67B395 (Alan Stewart <stewarta@vmware.com>
)
Signed By: Key 0x6163CB9E (Stefan Schmidt <schmidts@vmware.co m>)
Subkey ID: 0x411B8828 [RSA_GENERAL]
...
You can permanently trust the keyholder of this key by issuing the pgp trustcommand:
roo> pgp trust --keyId 0x0E5BA660 Added trust for key:
Enough OSGi to be dangerous 275
>>>> KEY ID: 0x0E5BA660 <<<<
More Info: http://keyserver.ubuntu.com/pks/lookup? ➥
fingerprint=on&op=index&search=0x0E5BA660 Created: 2010-Aug-05 14:43:59 +0000
Fingerprint: f2b858c56bcbada85df77995c74ccbff0e5ba660 Algorithm: DSA
User ID: Stefan Bley <stefan.bley@saxsys.de>
Signed By: Key 0x0E5BA660 (Stefan Bley <stefan.bley@saxsys.d e>)
Subkey ID: 0xB14BD4B7 [ELGAMAL_ENCRYPT]
This command, unlike pgp automatic trust, is a permanent decision and is kept within Roo’s configuration. If you upgrade to a new version of Roo, you may have to redo your trust relationships. You can also untrust a PGP key:
roo> pgp untrust --keyId 0xACB27429 Revoked trust from key:
>>>> KEY ID: 0xACB27429 <<<<
More Info: http://keyserver.ubuntu.com/pks/lookup? ➥
fingerprint=on&op=index&search=0xACB27429 Created: 2010-Jun-13 15:14:48 +0000
Fingerprint: 8f19905b317143e44bd28ba83fec2947acb27429 Algorithm: RSA_GENERAL
User ID: Christian Tzolov <christian@tzolov.net>
Signed By: Key 0xACB27429 - not locally trusted Subkey ID: 0xD9D8D1C2 [RSA_GENERAL]
11.3.6 Removing add-ons
To remove an add-on, use the addon remove command. This command is tab- completion aware, so if you aren’t sure which add-on you want to remove, keep hitting [TAB] to autocomplete the bundleSymbolicName command-line property:
roo> addon remove --bundleSymbolicName ➥
org.springframework.roo.addons.git Successfully removed add-on:
org.springframework.roo.addons.git
ADD-ON REMOVAL DOESN’T ALWAYS REMOVE CODE Code contributed by the add-on generally stays put. But nothing will keep it up to date, so you may want to use push-in refactoring to put the code under developer control again. As the add-on developer, you may wish to provide a remove command so that you can clean up after yourself before developers uninstall your add-on.
This command removes the artifact from the Roo installation’s bundle cache directory.