Roboconf's Maven plug-in

Roboconf’s Maven plug-in allows to automate some tasks related to Roboconf.
It also allows a seamless integration with build tools, such as Jenkins or Travis.

Here is a sample pom.xml file for a Roboconf project.

<?xml version="1.0" encoding="UTF-8"?>
<project 
		xmlns="http://maven.apache.org/POM/4.0.0" 
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
		xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

	<modelVersion>4.0.0</modelVersion>
	<prerequisites>
		<maven>3.0.3</maven>
	</prerequisites>

	<groupId>net.roboconf</groupId>
	<artifactId>my-project</artifactId>
	<version>1.0-SNAPSHOT</version>
	<name>This is a sample</name>
	<packaging>roboconf-app</packaging>

	<build>
		<plugins>
			<plugin>
				<groupId>net.roboconf</groupId>
				<artifactId>roboconf-maven-plugin</artifactId>
				<version>0.5</version>
				<extensions>true</extensions>
			</plugin>
		</plugins>
	</build>
</project>

There are 2 things to notice.

• The roboconf-app packaging, which indicates to Maven this is a Roboconf project.
• The roboconf-maven-plugin declaration in the build section.

The project structure must be the following one.

- pom.xml
- src/main/model/
** descriptor/
** graph/
** instances/

Basically, this is the usual Roboconf structure, translated into a Maven-like project.

Maven archetype

Use the following command to create a new Roboconf project from our Maven archetype.

mvn archetype:generate                              \
  -DarchetypeGroupId=net.roboconf                   \
  -DarchetypeArtifactId=roboconf-maven-archetype    \
  -DarchetypeVersion=1.0                            \
  -DgroupId=<my.groupid>                            \
  -DartifactId=<my-artifactId>

Maven Properties

Filtering is enabled in the Roboconf Maven plug-in.
It means you can inject Maven properties in your resource files.

Example with the application.properties file:

application-name = Tomcat 8 cluster
application-qualifier = ${project.artifactId}-${project.version}

# Etc.

Maven Goals

The plug-in has the following goals.

initialize

This goal configures the project (model directory, build output).
It has no parameter.

Users are not supposed to invoke this goal manually.
It is part of the default life cycle for roboconf-app projects.

validate-project

This goal validates the project’s structure.
It has no parameter.

Users are not supposed to invoke this goal manually.
It is part of the default life cycle for roboconf-app projects.

validate-application

This goal validates the Roboconf application.
It is part of the default life cycle for roboconf-app projects. You can also invoke it manually.

mvn roboconf:validate-application

Its configuration accepts the following parameters.

package

This goal packages a Roboconf application as a ZIP file.
It has no parameter.

It is part of the default life cycle for roboconf-app projects. You can also invoke it manually.

mvn package

… or the verbose way…

mvn roboconf:package

documentation

This goal generates documentation from the configuration files.
Documentation includes text documents and images (as PNG files). It lists all the components of the application and their relations. Generated documents can be used by people in charge production environments, as well as for maintenance teams.

This goal must be invoked explicitly.

mvn roboconf:documentation

It accepts the following parameters.

Available options for the documentation generator.

You can find examples of configuration here.

In addition to the default output, users can include additional information in their project.
The generator will read and include them in the result.

Thus, if you want to add a specific description for a component called toto, you can add a toto.summary.txt file under src/main/doc. Locales are supported too. Assuming you want to have one version for English and one for French, you will only have to add toto_en_US.summary.txt and toto_fr_FR.summary.txt under src/main/doc.

summary.txt files aim at adding a specific description of a given Roboconf component. It will be added at the beginning of a component’s description. You can also add information at the end of its dedicated section by using extra.txt files. As an example, if you want to add a warning or a caution section, you can add toto.extra.txt, toto_en_US.extra.txt or toto_fr_FR.extra.txt under src/main/doc.

For recipes, information ca be specified for facets.
To document a facet, create a file called your-facet-name.facet.txt. As usual, when you want to specify a locale, add it as a suffix (your-facet-name_en_US.facet.txt).