Documenting your custom Apache Camel components

This post is a follow-up of my previous post about building custom Apache Camel components. Below I expose some guidelines in order to document your Camel components and routes.

After digging here, here and here, as well as asking some questions on Claus’s blog, I came up with a list of possible solutions to document your custom Camel components and routes:

  • Generate Dot graphs to describe your routes, using the camel-maven-plugin [DEPRECATED]
  • Generate a properties file to list your components, using the camel-package-maven-plugin
  • Generate HTML and Json files to describe your component attributes, using the @UriEndpoint and @UriParam annotations together with camel-apt tooling
  • Generate Javadoc using the maven-javadoc-plugin
  • Use Hawtio to view your routes in a graph (and make a screenshot!)

Solution 1: Generate Dot graphs to describe your routes [DEPRECATED]

As stated above, this solution is deprecated, as the camel-maven-plugin “dot” goal is not being maintained anymore by the Apache community; but I mention it here for sake of completeness, and because it represents a convenient way of automatically generating a graph-oriented description of your route. You will need camel-maven-plugin in your Maven pom.xml. Also, as that plugin is based on Spring, you will need camel-spring on your classpath together with a Spring-XML-based description of your route.

Describe your Camel route (for instance the custom Feedly-based route from the previous post example) in a Spring applicationContext.xml file:

<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:camel="http://camel.apache.org/schema/spring" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

<camel:camelContext>

<camel:propertyPlaceholder id="properties" location="feedly.properties"/>

<camel:route>

<camel:from uri="feedly://search/feeds?delay={{delay}}&query={{query}}"/>

<camel:split>

<camel:simple>body</camel:simple>

<camel:log message="${in.body}"/>

</camel:split>

</camel:route>

</camel:camelContext>

</beans>

Complete your Maven pom.xml:

<dependencies>

...

<dependency>

<groupId>org.apache.camel</groupId>

<artifactId>camel-spring</artifactId>

<version>2.15.1</version>

<scope>provided</scope>

</dependency>

...

</dependencies>

<build>

<plugins>

...

<plugin>

<groupId>org.apache.camel</groupId>

<artifactId>camel-maven-plugin</artifactId>

<version>2.15.1</version>

<configuration>

<applicationContextUri>applicationContext.xml </applicationContextUri>

<useDot>true</useDot>

</configuration>

</plugin>

...

</plugins>

</build>

Running your route with the camel:run goal results in the creation of dot files under the /target/site/cameldoc folder, which can be then opened with GraphViz. Hereafter an example of what it looks like:

Solution 2: Generate a properties file to list your components

This solution provides a basic properties file describing the Camel components implemented in your artifact. Simply add the following to your pom.xml file:

<build>

<plugins>

...

<plugin>

<groupId>org.apache.camel</groupId>

<artifactId>camel-package-maven-plugin</artifactId>

<version>${camel-version}</version>

<executions>

<execution>

<goals>

<goal>generate-components-list</goal>

</goals>

<phase>generate-resources</phase>

</execution>

</executions>

</plugin>

...

</plugins>

</build>

Building our Maven project results in the generation of the /target/generated/camel/components/META-INF/services/org/apache/camel/component.properties file, with the contents below for our Feedly custom component:

version=0.0.1-SNAPSHOT

projectName=camel-custom-feedly-component

groupId=com.paloit.examples

components=feedly

artifactId=camel-custom-feedly-component

Solution 3: Generate HTML and Json files to describe your component attributes

This very promising way of generating documentation is based on annotation processing and uses the Camel @UriEndpoint, @UriParam and @UriParams annotations (which we used in our previous custom Feedly component example). It simply requires to add the camel-apt dependency to your pom.xml:

<dependencies>

...

<dependency>

<groupId>org.apache.camel</groupId>

<artifactId>apt</artifactId>

<version>2.15.1</version>

<scope>provided</scope>

</dependency>

...

</dependencies>

In our Feedly example case, building the Maven project results in the generation of the feedly.html and feedly.json files which are packed in the JAR next to our custom component class files.

feedly.html:

Scheme: feedly

  • feeds
Name Kind Type Required Deprecated Default Value Enum Values Description
query parameter java.lang.String true false
delay parameter int false false 60000

feedly.json:

{
"component": {
"kind": "component",
"scheme": "feedly",
"syntax": "feedly://operationPath",
"title": "Feedly",
"description": "Custom Feedly component",
"label": "feeds",
"consumerOnly": "true",
"javaType": "com.paloit.examples.camel.custom.feedly.FeedlyComponent",
"groupId": "com.paloit.examples",
"artifactId": "camel-custom-feedly-component",
"version": "0.0.1-SNAPSHOT"
},
"properties": {
"query": { "kind": "parameter", "type": "string", "javaType": "java.lang.String", "deprecated": "false" },
"delay": { "kind": "parameter", "type": "integer", "javaType": "int", "deprecated": "false", "defaultValue": "60000" }
}
}

Solution 4: Generate Javadoc

Generating javadoc for all your Java components is always a good and highly-customizable practice; it basically requires adding some comments to your sources and using the maven-javadoc-plugin in your pom.xml to automatically pack your doc into a JAR:

<build>

<plugins>

...

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-javadoc-plugin</artifactId>

<version>2.9.1</version>

<executions>

<execution>

<goals>

<goal>jar</goal>

</goals>

</execution>

</executions>

</plugin>

...

</plugins>

</build>

Solution 5: Use Hawtio to view your routes in a graph

If you want to document your routes, you can also use hawtio, which is a free plugin-based web console tool, useful to monitor pretty much everything in a visual way, including your Camel routes. Just download the tool on their website and run the JAR:

java -jar hawtio-app-1.4.49.jar

Note that you need to use the same JRE/JDK environment to run both hawtio and the Camel route, in order for hawtio to detect the Camel context and make the specific monitoring options available in the UI. Once your Camel route and hawtio are started, go to the local hawtio connection page (http://localhost:8080/hawtio/jvm/local), identify your Camel JVM instance (e.g. com.paloit.examples.camel.custom.feedly.Main) and click on the “Start agent” button on the right. Then click on the Agent URL displayed on the right and the Camel tab will appear in the top navigation bar. Finally, click on that tab, go to the “Routes” section in the Contexts tree, select your route and use the “Route Diagram” tab on the right to display the graph of your route:

Although the purpose of this graph is to monitor the number of executions of each Camel endpoint, you can still make a screenshot out of it and use if for your documentation (hoping that the hawtio guys will implement someday an “export” button 😉 ).

Next steps

You can find the complete sources for this example on our GitHub: https://github.com/Palo-IT/Examples/tree/master/camel-custom-feedly-component

Share
Alexandre ESTELA

2553

Leave a Reply

Your email address will not be published. Required fields are marked *