search

ncasaux / camel-plantuml

camel-plantuml allows to generate PlantUML diagrams from deployed Camel routes
MIT License
37 stars 6 forks source link
camel diagram plantuml uml visualization

readme

Overview

camel-plantuml is a tool which helps to generate PlantUML activity diagrams which describe Apache Camel routes, based on an actual running Camel context.

It allows to have diagrams where you can see interactions between endpoints and routes.

If you consider following routes:

from(timer("foo").period(5000)).id("slowTimerRoute")
        .description("Route which generates slow periodic events")
        .setBody(constant("slow"))
        .to(seda("endpoint1"));

from(timer("bar").period(1000)).id("fastTimerRoute")
        .description("Route which generates fast periodic events")
        .setBody(constant("fast"))
        .to(seda("endpoint1"));

from(seda("endpoint1")).id("mainRoute")
        .description("Route which handles processing of the message")
        .log(LoggingLevel.INFO, "${body}")
        .enrich().constant("direct://endpoint2")
        .toD(mock("mock-${body}"));

from(direct("endpoint2")).id("transformRoute")
        .description("Route which transforms the message")
        .transform(simple("${body}${body}"));

It will allow you to generate these images:

This tool is intended to be a software documentation tool, it is not intended to be a monitoring tool with real-time metrics or statistics.

How it works

This tool needs to have access to a running Camel context instance. It uses the Camel JMX MBeans (which are enabled by default in Camel), and particularly the ones related to routes and processors. Therefore, this tool does NOT work during design time or coding of the Camel routes. It requires an actual running Camel context.

Following processors are handled:

It parses the processors to extract URI(s) information. If an expression is found, then, based on the language of the expression:

  1. If the language is constant, it will consider it as a static endpoint (which could be used in other processors or routes).
  2. If the language is simple, it will consider it as a dynamic endpoint (with no possible link with other processors or routes).
  3. Otherwise, it will ignore the endpoint.

The PlantUML code is exposed through a configurable HTTP endpoint, so it can be re-worked, and finally rendered as an image.

Features

This tool generates PlantUML diagrams with following features:

How to use ?

This tool can be used in two different ways:

Option 1: embedded mode

In this mode, the tool is embedded within your project and connects directly to the MBean server of your application's JVM. The tool exposes the UML diagram directly from your application through a dedicated HTTP endpoint.

1. Add the dependency to your project:

The jar is a OSGi bundle, hence it can be used with Apache ServiceMix/Apache Karaf.

<dependency>
    <groupId>io.github.ncasaux</groupId>
    <artifactId>camel-plantuml-jar</artifactId>
    <version>x.y.z</version>
</dependency>

Based on the Apache Camel version you use, choose the correct version:

Apache Camel version camel-plantuml version
<= 3.15 1.3.x
>= 3.16 and <= 3.19 1.4.x
>= 3.20 1.5.x
>= 4.0 1.6.x
>= 4.4 >=1.7.x

2. Add the route builder to your Camel context:

getContext().addRoutes(new CamelPlantUmlRouteBuilder());

Default host is localhost, default port is 8090, but you can overide them:

getContext().addRoutes(new CamelPlantUmlRouteBuilder("localhost", 8090));

3. Start your Camel context, and open a browser:

To have all the endpoints, go to:

http://localhost:8090/camel-plantuml/diagram.puml

To connect routes directly (and hide "internal" endpoints), add the following parameter:

http://localhost:8090/camel-plantuml/diagram.puml?connectRoutes=true

To hide endpoints and/or routes which match a URI pattern (.*foo.* in following example), add the following parameter:

http://localhost:8090/camel-plantuml/diagram.puml?uriFilterPattern=.*foo.*

Option 2: remote mode

In this mode, the tool connects remotely to the MBean server of your application's JVM. The tool exposes the UML diagram directly from its dedicated HTTP endpoint. The tool is packaged as a zip file.

1. Download the zip file:

Download the latest release from here

Unzip it in the folder of your choice and go into this folder.

2. Enable JMX unsecure connection in your application

Start your application with following parameters and port of your choice:

-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.port={{JMX_PORT}}
-Djava.rmi.server.hostname={{YOUR_APPLICATION_IP}}

3. Connect the tool to your application

Start locally the tool with parameter jmxHost:

java -DjmxHost={{YOUR_APPLICATION_IP}}:{{JMX_PORT}} -jar camel-plantuml-zip-x.y.z.jar

4. Open a browser:

To display all the endpoints, go to:

http://localhost:8090/camel-plantuml/diagram.puml

To connect routes directly (and hide "internal" endpoints), add the following parameter:

http://localhost:8090/camel-plantuml/diagram.puml?connectRoutes=true

To hide endpoints and/or routes which match a URI pattern (.*foo.* in following example), add the following parameter:

http://localhost:8090/camel-plantuml/diagram.puml?uriFilterPattern=.*foo.*

Rendering the PlantUML Code

There are multiple options:

FAQ

  1. What are the differences with the Camel plugin for hawtio ?

The Camel plugin for hawtio has also a graphical representation of routes and route steps. However, there is no graphical connection between routes directly, as each route is drawn individually. So you can not know the routes/endpoints interconnections. That is the main purpose of this tool.

  1. Why this tool can not expose directly the images of the diagrams, instead (or along with) the PlantUML code?

This tool is based on legacy PlantUML activity diagrams. To draw such diagrams, Graphviz is required, and unfortunately, there is no Java implementation of Graphviz...

  1. So, why don't this tool use the new PlantUML activity diagrams, which do not require Graphviz anymore ?

As far as I know, the new activity diagram is not intended to create connections between any two actions, and that's completely incompatible with diagrams this tool aims to create.

Contributing

Any suggestion, remark, or question? Feel free to create an issue and/or to contribute by forking and making pull requests!

Releases notes

v1.8.0

v1.7.0

v1.6.0

v1.5.0

v1.4.0

v1.3.0

v1.2.1