In addition to the general installation steps discussed in the development process chapter (section 4), you should also follow the following project specific steps:

Once you have installed Java, Maven, PGP, and SVN tools, and have created and checked out your Google Code project, you can change into the <project-name> directory, which at this stage should contain only the .svn directory. In the <project-name> directory, you can start the Spring Roo shell and use one of the new commands for add-on creation:

roo> addon create simple --topLevelPackage com.foo --projectName <project-name>

The addon create simple command will scaffold a number of artefacts:

[1] pom.xml
[2] readme.txt
[3] legal/LICENSE.TXT
[4] src/main/java/com/foo/batch/BatchCommands.java
[5] src/main/java/com/foo/batch/BatchOperations.java
[5] src/main/java/com/foo/batch/BatchOperationsImpl.java
[6] src/main/java/com/foo/batch/BatchPropertyName.java
[7] src/main/assembly/assembly.xml

This newly created add-on project can be imported into the SpringSource Tool Suite via File > Import > Maven > Existing Maven projects. Let's discuss some of these artefacts in more detail:

Spring Roo provides an easy way for external add-ons to contribute new commands to the Roo Shell. Looking at the code extract below, there are really only two artefacts needed in your command type to register a new command in the Roo Shell; your type needs to implement the CommandMarker interface, and you need to create a method annotated with @CliCommand. Let us review some details:

[1] @Component
[1] @Service
[2] public class BatchCommands implements CommandMarker {

[3]    @Reference private BatchOperations operations;
       @Reference private StaticFieldConverter staticFieldConverter;

[4]    protected void activate(ComponentContext context) {
          staticFieldConverter.add(BatchPropertyName.class);
       }

[4]    protected void deactivate(ComponentContext context) {
          staticFieldConverter.remove(BatchPropertyName.class);
       }

[5]    @CliAvailabilityIndicator("welcome property")
       public boolean isPropertyAvailable() {
          return operations.isProjectAvailable();  
       }

[6]    @CliCommand(value="welcome property", help="Obtains a pre-defined system property")
[7]    public String property(@CliOption(key="name", mandatory=false, specifiedDefaultValue="USERNAME", unspecifiedDefaultValue="USERNAME", help="The property name you'd like to display") BatchPropertyName propertyName) {
          return operations.getProperty(propertyName);
       }

There are a few artefacts of interest when developing Spring Roo add-ons:

Almost all Spring Roo add-ons provide operations types. These types do most of the work behind Roo's passive generation principle (active generation is taken care of by AspectJ Intertype declarations (ITDs) - more about that later). Methods offered by the operations types provided by the add-on are typically invoked by the accompanying "command" type. Alternatively, operations types can also be invoked by other add-ons (this is a rather unusual case).

Implementations of the Operations interface need to be annotated with the Felix @Component and @Service annotations to make their functionality available within Roo's OSGi container. Dependencies can be injected into operations types via the Felix @Reference annotation. If the dependency exists in a package that is not yet registered in the add-on's pom.xml, you need to add the dependency there to add the relevant bundle to the add-on's classpath.

The Add-On Creator generated project includes example code which uses Roo's source path abstractions, file manager and various Util classes that take care of project file management.

Typical functionality offered by operations types include:

Spring Roo offers a wide range of abstractions and metadata types that support these use cases. For example, the following services are offered:

In addition the org.springframework.roo.support bundle provides a number of useful utils classes:

Once your add-on is complete, you can test its functionality locally by generating an OSGi-compliant jar bundle and installing it in the Spring Roo Shell:

<project-name>$ mvn clean install

This will generate your add-on OSGi bundle in the project's target directory. In a separate directory, you can start the Spring Roo Shell and use the following command to test your new add-on:

roo> osgi start --url file:///<path-to-addon-project/target/<addon-bundle-name>.<version>.jar

This should install and activate your new Spring Roo Add-On. For troubleshooting, Roo offers the following OSGi commands:

Once you have tested the add-on successfully in your development environment, you can release the add-on source code to your Google Code project, create a tag, and install all relevant artifacts in the project's Maven repository:

<project-name>$ svn add pom.xml src/ legal/ readme.txt

<project-name>$ svn commit -m "initial commit"

<project-name>$ mvn release:prepare release:perform 

The Maven release plugin will ask for tag and release artefact names. Roo follows the OSGi convention of using the major, minor and micro version numbers followed by a textual identifier, e.g. 0.1.1.RELEASE, 0.1.2.BUILD-SNAPSHOT, etc.

Deployment for bundles created with Roo's "wrapping" command can be deployed rather than released. For example, to create a wrapped bundle of the PostgreSQL JDBC driver, use this command:

roo> addon create wrapper --topLevelPackage com.foo.wrapper --projectName spring-roo-postgres-wrapper --artifactId postgresql \
--groupId postgresql --version 9.0-801.jdbc3 --description "Postgres #jdbcdriver driverclass:org.postgresql.Driver." \
--licenseUrl http://jdbc.postgresql.org/license.html --docUrl http://jdbc.postgresql.org/ --vendorName "The PostgreSQL Global Development Group"

This can then be deployed to a Google code project (set up in the same way as described above) with a simple deploy command:

<project-name>$ mvn deploy

Once the release is complete, check your Google Code project to see that your add-on's pom.xml has been updated to the new version (e.g. 0.1.2.BUILD-SNAPSHOT), that a new tag has been committed to the tags directory, and that the repo directory has been populated with all the artifacts seen in a typical Maven repository. All artefacts have been signed with your private PGP key, and your public key is available in the relevant .asc files. In the repo directory, you should also find the repository.xml file which contains all relevant information for an OSGi OBR repository.

The URL to the raw (see sidebar) repository.xml artefact can then be registered with RooBot:

Register your new add-on repository by sending an email to [email protected] where the subject line MUST be the raw URL to OSGi repository.xml. The email body is not currently used (but you can send greetings to the Roo team ;-). Other registration methods are being considered (web front-end, Roo shell command, etc).

RooBot verifies a few aspects before publishing your new add-on to the community:

If all tests pass, RooBot will publish your add-on in a publicly accessible XML registry http://spring-roo-repository.springsource.org/roobot/roobot.xml. This registry is available to the RooBot client integrated into the Spring Roo Shell.

Once you have sent your email to [email protected], you should receive a response from RooBot indicating that the processing of your repository has started. If successful, you will see your add-on listed at http://spring-roo-repository.springsource.org/roobot/roobot.xml within a few hours. If this does not happen, you can visit the RooBot error log at http://spring-roo-repository.springsource.org/roobot/roobot-log.txt, which is refreshed every 5 minutes.

Once RooBot has published your add-on sucessfully, it will periodically process your repository to verify its ongoing validity. As part of this periodic processing, it will also automatically pick up new versions (add-on releases) in your repository.xml. Therefore it should not be necessary to explicitly notify RooBot of any changes in your repository.

As OSGi is the runtime platform for Roo 1.1.0 onwards, porting addons from a previous version will require some small tweaks to your code. Here's a step-by-step guide on what you need to do: