The following code listing shows the MysimpleCommands class, which defines the commands that the add-on contributes to the Roo shell:

import java.util.logging.Logger;
import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Reference;
import org.apache.felix.scr.annotations.Service;
import org.springframework.roo.shell.converters.StaticFieldConverter;

@Component
@Service
public class MysimpleCommands implements CommandMarker { 
	
  private Logger log = Logger.getLogger(getClass().getName());

  @Reference private MysimpleOperations operations; 
	
  @Reference private StaticFieldConverter 
     staticFieldConverter;

  protected void activate(ComponentContext context) {
    staticFieldConverter.add(MysimplePropertyName.class);
  }

  protected void deactivate(ComponentContext context) {
    staticFieldConverter.remove(MysimplePropertyName.class);
  }
  ...
}

The following are some of the important points to note about the MysimpleCommands class:

import org.springframework.roo.shell.CliCommand;
import org.springframework.roo.shell.CliOption;
...

@Reference private MysimpleOperations operations; 

@CliCommand(value = "say hello", 
  help = "Prints welcome message to the Roo shell")
public void sayHello(
   @CliOption(key = "name", mandatory = true, 
     help = "State your name") String name, 
   @CliOption(key = "countryOfOrigin", mandatory = false, 
     help = "Country of orgin") MysimplePropertyName country) {

    log.info("Welcome " + name + "!");
   ...
}

@CliCommand(value = "web mvc install tags", 
  help="Replace default Roo MVC tags used for scaffolding")
public void installTags() {
   .installTags();
}

The MysimpleOperations interface defines three methods as described in the following table:

The MysimpleOperationsImpl class implements the MysimpleOperations interface. The methods defined in the MysimpleCommands class mainly delegate processing of logic to the implementation of the MysimpleOperations interface. The following code shows the MysimpleOperationsImpl class (methods have not been shown for brevity):

import org.springframework.roo.process.manager.FileManager;
import org.springframework.roo.project.ProjectOperations;

@Component
@Service
public class MysimpleOperationsImpl 
   implements MysimpleOperations {
  private static final char SEPARATOR = File.separatorChar;

  @Reference private FileManager fileManager;

  @Reference private ProjectOperations projectOperations;
  ...
}

The MysimpleOperationsImpl class is annotated with @Component and @Service Apache Flex annotations, which means OSGi's SCR is responsible for managing the lifecycle of the MysimpleOperationsImpl component and registering it as a service with the OSGi service registry. Like MysimpleCommands, you can access the MysimpleOperationsImpl instance from other add-ons using the @Reference Apache Felix annotation.

Roo provides many built-in services which simplify add-on development. FileManager and ProjectOperations types represent services provided by Roo for managing files (like creating, reading, updating files, undo capability, and so on) and performing actions on the Roo project (like adding dependencies to the pom.xml file, updating project type, and so on), respectively. FileManager service and ProjectOperations are provided by the Process Manager and Project core modules of Roo, respectively. It is important to note that add-ons are different from core modules in Roo. The core modules provide vital features of the Spring Roo tool, like file system monitoring, registering commands with the Roo shell, and so on. Roo commands provided by add-ons are executed by Spring Roo users for code generation but Roo commands provided by core modules are primarily meant for accessing internal features of Spring Roo, like obtaining metadata, setting polling speed, and so on.

We saw earlier that the isInstallTagsCommandAvailable method of MysimpleOperations is invoked by the isInstallTagsCommandAvailable method of the MysimpleCommands class to check the availability of the web mvc install tags command. The following code shows the isInstallTagsCommandAvailable method of MysimpleOperationsImpl:

public boolean isInstallTagsCommandAvailable() {
    return 
     projectOperations.isProjectAvailable() && 
     fileManager.exists(projectOperations.getProjectMetadata()
     .getPathResolver().getIdentifier(Path.SRC_MAIN_WEBAPP,
     "WEB-INF" + SEPARATOR + "tags"));
}

In the code, the isInstallTagsCommandAvailable method makes use of ProjectOperation services to check if a Roo project exists. The method also makes use of the FileManager service to check if a tags sub-directory exists in the SRC_MAIN_WEBAPP/WEB-INF directory of your Roo project. If a tags directory doesn't exist or you haven't yet created a Roo project, then the method returns false. This means the web mvc install tags Roo command is not available to the Roo shell if you haven't yet created a Roo project which contains a tags sub-directory inside the SRC_MAIN_WEBAPP/WEB-INF directory.

We saw earlier that the installTags method of MysimpleCommands invokes the installTags method of MysimpleOperations. The following code shows the installTags method as implemented by the MysimpleOperationsImpl class:

import org.springframework.roo.process.manager.MutableFile;
import org.springframework.roo.project.Path;
import org.springframework.roo.project.PathResolver;
import org.springframework.roo.project.ProjectOperations;
import org.springframework.roo.support.util.FileCopyUtils;
import org.springframework.roo.support.util.TemplateUtils;
...
public void installTags() {
  PathResolver pathResolver = 
    projectOperations.getProjectMetadata().getPathResolver();

    createOrReplaceFile(..., "info.tagx");
    createOrReplaceFile(..., "show.tagx");
}

private void createOrReplaceFile(String path, String fileName) 
{
  String targetFile = path + SEPARATOR + fileName;

  MutableFile mutableFile = fileManager.exists(targetFile) ? 
   fileManager.updateFile(targetFile) : 
   fileManager.createFile(targetFile);
  try {
    FileCopyUtils.copy(TemplateUtils.getTemplate(getClass(),
    fileName), mutableFile.getOutputStream());
  } catch (IOException e) {
    throw new IllegalStateException(e);
 }
}

In the code, the installTags method copies info.tagx and show.tagx files from the SRC_MAIN_RESOURCE/com/roo/addon/mysimple directory of the mysimple add-on to the SRC_MAN_WEBAPP/WEB-INF/tags directory of your Roo project. The createOrReplace method is the method, which is used by the installTags method to copy the files. The following table describes the classes used by the installTags and createOrReplace methods for copying tag files:

Let's now look at the MysimplePropertyName enum type, which defines constants for the countryOfOrigin argument of web mvc install tags command.

The following code shows the MysimpleNameProperty enum type, which defines constants for the countryOfOrigin argument value of the web mvc install tags command:

public enum MysimplePropertyName {
    AUSTRALIA("Australia"),
    UNITED_STATES("United States"),
    GERMANY("Germany"),
    NOT_SPECIFIED("None of your business!");
    
    private String propertyName;
    
    private MysimplePropertyName(String propertyName) {
        Assert.hasText(propertyName, "Property name required");
    this.propertyName = propertyName;
    }
   ...
}

In the code, constant AUSTRALIA is associated with value Australia, UNITED_STATES is associated with value United States, and so on. We saw earlier that the countryOfOrigin argument is of type MysimplePropertyName . We can only pass String type values for an argument from the Roo shell, so what we should specify as the value of the countryOfOrigin argument, and how it'll get converted to MysimplePropertyName. When you enter a partial value for the countryOfOrigin argument and press the Tab key, Roo internally refers to MysimplePropertyName to find a matching constant. For instance, if you enter au as the value of the countryOfOrigin argument, Roo attempts to find the constant that matches au in MysimpleNameProperty and auto-completes the value. As the matching is case-insensitive, the value au of the countryOfOrigin argument is completed by the Roo shell as AUSTRALIA.

The following diagram summarizes how a simple add-on works:

The figure shows that CommandMarker is an interface provided by Roo, and it is implemented by the MysimpleCommands class. The MysimpleCommands class invokes methods of the MysimpleOperationsImpl class to process the commands exposed by the mysimple add-on. The MysimpleCommands and MysimpleOperationsImpl classes use services provided by Roo to perform the desired functionality.

Once you have created an add-on, you may want to test its functionality, before making the add-on available to other developers. In this section, we'll look at how to locally deploy and test the mysimple add-on that we created using the create addon simple command.

To use the mysimple add-on, you need to convert it into an OSGi-compliant JAR bundle. To do so, execute mvn clean install from the directory which contains your mysimple add-on project, as shown here:

C:
oo-cookbookch07-simple-add-on> mvn clean install -Dgpg.passphrase=<thephrase>

Here, <thephrase> is the password phrase that you provide for signing add-ons using GnuPG (also referred to as GPG). Refer to the Setting up GnuPG for add-on development recipe for information on how to set up GnuPG and create a password phrase for signing add-ons.

Executing the mvn clean install command creates a com.roo.addon.mysimple-0.1.0.BUILD-SNAPSHOT.jar add-on OSGi bundle in the target directory of the mysimple add-on project. Now, let's look at how to use the mysimple add-on in a Roo project.

roo> osgi update --url file:///C:/roo-cookbook/ch07-simple-add-on/target/com.roo.addon.mysimple-0.1.0.BUILD-SNAPSHOT.jar

roo> osgi uninstall --bundleSymbolicName com.roo.addon.mysimple

The MysimplePropertyName enum type defines constants, which represent the possible values that an argument of a Roo command can accept. You are not limited to using enum types to define constants for argument values. Let's say that instead of using the MySimplePropertyName enum type we want to use a Country class that defines constants for countries. The following code shows the Country class that can be used in place of the MySimplePropertyName enum type:

public class Country {
 public static final Country AUSTRALIA = 
     new Country("Australia");
 public static final Country NOT_SPECIFIED = 
     new Country("None of your business!");
 public static final Country UNITED_STATES = 
     new Country("United States");
 public static final Country GERMANY = 
     new Country("Germany");
 
 private String countryName;
 
 public Country(String countryName) {
  this.countryName = countryName;
 }
 
 public String getCountryName() {
  return countryName;
 }
}

The preceding code shows that the Country class defines constants for each country representing a possible value of the countryOfOrigin argument. Now, to use the Country class instead of the MysimplePropertyName enum, all you need to do is to replace references to it with Country in the MysimpleCommands class, as shown here:

public class MysimpleCommands implements CommandMarker { 
 @Reference private StaticFieldConverter staticFieldConverter;

 protected void activate(ComponentContext context) {
  staticFieldConverter.add(Country.class);
 }

 protected void deactivate(ComponentContext context) {
  staticFieldConverter.remove(Country.class);
 }
 
 @CliCommand(value = "say hello", 
    help = "Prints welcome message to the Roo shell")
 public void sayHello(..., @CliOption(key = "countryOfOrigin", 
     mandatory = false, 
     help = "Country of orgin") Country country) {
  
  log.info("Welcome " + name + "!");
  log.warning("Country of origin: " + (country == null ? 
     Country.NOT_SPECIFIED.getCountryName() : 
     country.getCountryName()));
  ...
 }
 ...
}

The preceding code shows that the Country class must be added to the StaticFieldConverter service and must be specified as the type of countryOfOrigin argument in sayHello method.

In mysimple add-on, separate @CliAvailabilityIndicator annotated methods are used to indicate availability of the say hello and web mvc install tags commands. If you want to use a single @CliAvailabilityIndicator annotated method to indicate availability of multiple Roo commands offered by the mysimple add-on, then specify the command array in the @CliAvailabilityIndicator annotation. For instance, you can define the following method in MysimpleCommands to indicate that the say hello and web mvc install tags commands are always available to the Roo shell:

@CliAvailabilityIndicator({"say hello", 
  "web mvc install tags"})
public boolean isCommandAvailable() {
     return true; 
}

In the preceding code the @CliAvailabilityIndicator annotation specifies an array of Roo commands (say hello and web mvc install tags) whose availability is checked by the isCommandAvailable method.

Templates in an add-on project are resources that are copied to the Roo project when one or more commands of the add-on are executed. For instance, when you execute the web mvc install tags command, the info.tagx and show.tagx files are copied from add-on to the Roo project. Templates can also be images, XML files, properties files, and so on, which the add-on commands copy to the Roo project.

Templates are located inside the SRC_MAIN_RESOURCES directory of an add-on project. For instance, in the case of the mysimple add-on, the info.tagx and show.tagx files are located in the SRC_MAIN_RESOURCES/com/roo/addon/mysimple directory. Add-ons access templates using the TemplateUtils class and then copy it to the Roo project using the FileCopyUtils class. TemplateUtils defines the following two static methods which are used to access templates in the add-on:

In some add-ons, a template file may be an XML file which the add-ons need to modify before copying it to the Roo project. To modify XML templates, Roo provides an XMLUtils class which add-ons can use to modify the content of XML template files. Let's look at a scenario that shows how add-ons can modify the content of an XML template file before copying it to the Roo project.

The following config.xml file shows a Spring application context XML file which represents a template XML file of an add-on:

beans xmlns="http://www.springframework.org/schema/beans"
xmlns:context="http://www.springframework.org/schema/context" ...>
    <context:component-scan base-package=""/>
    ...
</beans>

In the config.xml file, the <component-scan> element of Spring's context namespace specifies the packages (via the base-package attribute) that are scanned by Spring. The classes in these packages (and their sub-packages) that are annotated with the @Component, @Service, and @Repository Spring annotations are auto-registered with Spring's application context. As the add-on copies the config.xml file to a Roo project when a Roo command is executed, the add-on doesn't know in advance the value that needs to be specified for the base-package attribute. This is the reason why the value of the base-package attribute is empty in the config.xml file.

The following code shows how an add-on can read the config.xml file, modify it, and then write the modified config.xml to the Roo project:

import org.springframework.roo.metadata.MetadataService;
import org.springframework.roo.project.PathResolver;
import org.springframework.roo.project.ProjectMetadata;
import org.springframework.roo.support.util.XmlUtils;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import java.io.ByteArrayOutputStream;
import java.io.OutputStreamWriter;

@Component
@Service
public class FileWriterOperationsImpl 
 implements FileWriterOperations {
@Reference private MetadataService metadataService;
 ...
 public void copyApplicationContextXML() {
  ProjectMetadata projectMetadata = 
  (ProjectMetadata) metadataService.get(ProjectMetadata.
                              getProjectIdentifier());

  InputStream templateInputStream =              
      TemplateUtils.getTemplate(getClass(), 
                                  "config.xml");
  Document config;
  try {
    config = XmlUtils.getDocumentBuilder().
                          parse(templateInputStream);
  } catch (Exception ex) {...}

  Element rootElement = (Element) config.getDocumentElement();
  
  XmlUtils.findFirstElementByName("context:component-scan", 
    rootElement).setAttribute("base-package",      
                   projectMetadata.getTopLevelPackage().
                   getFullyQualifiedPackageName());

  ByteArrayOutputStream outputStream = 
      new ByteArrayOutputStream();

  XmlUtils.writeXml(XmlUtils.createIndentingTransformer(), 
                      outputStream, 
                      config);
  String xmlContent = outputStream.toString();

  FileCopyUtils.copy(xmlContent, new OutputStreamWriter(...));
 }
 ...
}

The FileWriterOperationsImpl class is similar to the MysimpleOperationsImpl class of the mysimple add-on. It defines the copyApplicationContextXML method which is responsible for copying the config.xml file from the add-on to the Roo project.

The MetadataService class represents a service provided by Roo for retrieving metadata information for the Roo project, Java types, fields, methods, and so on. Metadata is obtained from Roo's MetadataService using a metadata identification string, which has the format: MID:<fully-qualified-class-name>#<instance-identification-key>, where <fully-qualified-class-name> is the metadata type and <instance-identification-key> is the Java type to which the metadata applies. If the metadata is not associated with a Java type, then the metadata string format is: MID:<fully-qualified-class-name>. If the metadata identification string has the format MID:<fully-qualified-class-name>#<instance-identification-key>, then it is referred to as an instance-level metadata identification string. If the metadata identification string has the format MID:<fully-qualified-class-name>, then it is referred to as a class-level metadata identification string. In the FileWriterOperationsImpl class, ProjectMetadata represents a metadata type which holds the Roo project's details, like project name, top-level package name, dependencies, and so on. The getProjectIdentifier() method of ProjectMetadata returns a metadata identification string for the Roo project and is then passed to MetadataService to retrieve the ProjectMetadata instance.

The TemplateUtils class is used to obtain java.io.InputStream to the config.xml file. The XmlUtils class is then used to parse the config.xml file to build the org.w3c.dom.Document instance. The findFirstElementByName method of XmlUtils is used to find the first occurrence of the <context:component-scan> element in config.xml. The findFirstElementByName method returns an instance of org.w3c.dom.Element. The setAttribute method of Element is used to set the value of the base-package attribute of the <context:component-scan> element to the top-level package of the Roo project. The writeXml method of XmlUtils writes the Document object to java.io.OutputStream. The createIndentingTransformer method of XmlUtils creates a javax.xml.transform.Transformer instance, which indents entries in the Document object by 4 characters. If you want to perform a custom transformation of XML, you can create a custom Transformer implementation and pass it to the writeXml method of XmlUtils class.

Let's say you have a Roo project named flight-app whose top-level package is com.sample.flightapp. Now assume that you execute a Roo command which results in the execution of the copyApplicationContextXML method of the FileWriterOperationsImpl class of the add-on. The copyApplicationContextXML method will read the config.xml template file, set the base-package attribute of the <context:component-scan> element to com.sample.flightapp and write the modified config.xml to the flight-app Roo project.

Now let's look at some of the important configurations defined in the pom.xml file of the mysimple add-on project.

The pom.xml file of an add-on created via the addon create simple command contains the following configurations:

Once you have deployed an add-on, you can check if it was successfully installed or not by using the following OSGi commands from the Roo shell: