You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2021/08/09 11:50:24 UTC
[camel] 05/05: Polish and cleanup documentation
This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
commit b3c644123fa400a51f5e3976e39e62810573bb57
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Mon Aug 9 13:48:15 2021 +0200
Polish and cleanup documentation
---
docs/pom.xml | 25 +++
.../modules/ROOT/pages/camel-maven-archetypes.adoc | 10 +-
.../modules/ROOT/pages/camel-maven-plugin.adoc | 176 +++++++++++++++------
.../ROOT/pages/camel-report-maven-plugin.adoc | 20 ++-
4 files changed, 176 insertions(+), 55 deletions(-)
diff --git a/docs/pom.xml b/docs/pom.xml
index 529795d..e701520 100644
--- a/docs/pom.xml
+++ b/docs/pom.xml
@@ -42,6 +42,31 @@
<build>
<plugins>
+ <!-- we want to copy some adoc files from tooling -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-resources-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy-maven-plugin-doc</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>copy-resources</goal>
+ </goals>
+ <configuration>
+ <outputDirectory>${basedir}/user-manual/modules/ROOT/pages</outputDirectory>
+ <resources>
+ <resource>
+ <directory>../tooling/maven/camel-maven-plugin/src/main/docs</directory>
+ </resource>
+ <resource>
+ <directory>../catalog/camel-report-maven-plugin/src/main/docs</directory>
+ </resource>
+ </resources>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
<plugin>
<groupId>com.github.eirslett</groupId>
<artifactId>frontend-maven-plugin</artifactId>
diff --git a/docs/user-manual/modules/ROOT/pages/camel-maven-archetypes.adoc b/docs/user-manual/modules/ROOT/pages/camel-maven-archetypes.adoc
index 9c49085..8de1d00 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-maven-archetypes.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-maven-archetypes.adoc
@@ -50,11 +50,13 @@ create a new Maven project for Camel routes using Endpoint DSL.
The maven coordinates for these archetypes is the following:
-[source,syntaxhighlighter-pre]
+[source,xml]
----
+<dependency>
<groupId>org.apache.camel.archetypes</groupId>
<artifactId>${archetype-name}</artifactId>
<version>${camel-version}</version>
+</dependency>
----
[[CamelMavenArchetypes-Snapshotarchetypes]]
@@ -63,14 +65,14 @@ The maven coordinates for these archetypes is the following:
If you would like to use an archetype from an unreleased version of
Camel, you just need to let the maven-archetype-plugin know where to
look for it. For example, say someone wanted to create a Java based
-project based on Camel 3.8.0-SNAPSHOT. He'd need to use the following command
+project based on Camel 3.12.0-SNAPSHOT. He'd need to use the following command
-[source,shell]
+[source,bash]
----
mvn archetype:generate \
-DarchetypeGroupId=org.apache.camel.archetypes \
-DarchetypeArtifactId=camel-archetype-java \
- -DarchetypeVersion=3.8.0-SNAPSHOT
+ -DarchetypeVersion=3.12.0-SNAPSHOT
----
When the project is created, you may need to add another repository to
diff --git a/docs/user-manual/modules/ROOT/pages/camel-maven-plugin.adoc b/docs/user-manual/modules/ROOT/pages/camel-maven-plugin.adoc
index b3aff4e..d7e134d 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-maven-plugin.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-maven-plugin.adoc
@@ -1,40 +1,63 @@
= Camel Maven Plugin
-The
-https://github.com/apache/camel/tree/main/tooling/maven/camel-maven-plugin[Camel
-Maven Plugin] allows you to run your
-xref:{eip-vc}:eips:enterprise-integration-patterns.adoc[Enterprise Integration
-Patterns] using xref:spring.adoc[Spring] for
-xref:dependency-injection.adoc[Dependency Injection] inside Maven.
+The Camel Maven Plugin supports the following goals
-== Goals Supported
+ - camel:run - To run your Camel application
+ - camel:prepare-fatjar - To prepare your Camel application for being packaged as a fat-jar (such as by maven-assembly-plugin)
-[width="100%",cols="34%,33%,33%",options="header",]
-|=======================================================================
-|Documentation |Goal |Description
-|xref:camel-run-maven-goal.adoc[camel:run] |camel:run |Boots up Camel in
-the context of a separately initiated Java thread using the
-xref:spring.adoc[Spring] configuration at *META-INF/spring/*.xml* and
-runs your routing rules. From Camel 2.10 onwards also OSGi blueprint is
-supported to load from *OSGI-INF/blueprint/*.xml* (requires to configure
-the plugin to use blueprint).
+== camel:run
-|=======================================================================
+The `camel:run` goal of the Camel Maven Plugin is used to run your Camel Spring configurations in a forked JVM from Maven.
+A good example application to get you started is the Spring Example.
+
+----
+cd examples/camel-example-spring
+mvn camel:run
+----
+
+This makes it very easy to spin up and test your routing rules without having to write a main(...) method;
+it also lets you create multiple jars to host different sets of routing rules and easily test them independently.
+
+How this works is that the plugin will compile the source code in the maven project,
+then boot up a Spring ApplicationContext using the XML configuration files on the classpath at `META-INF/spring/*.xml`
+
+If you want to boot up your Camel routes a little faster, you could try the `camel:embedded` instead.
+
+=== Options
+
+The maven plugin *run* goal supports the following options which can be configured from the command line (use `-D` syntax), or defined in the `pom.xml` file in the `<configuration>` tag.
+
+|===
+| Parameter | Default Value | Description
+| duration | -1 | Sets the time duration (seconds) that the application will run for before terminating. A value <= 0 will run forever.
+| durationIdle | -1 | Sets the idle time duration (seconds) duration that the application can be idle before terminating. A value <= 0 will run forever.
+| durationMaxMessages | -1 | Sets the duration of maximum number of messages that the application will process before terminating.
+| logClasspath | false | Whether to log the classpath when starting
+|===
-== Adding the plugin to your pom.xml
-Add the following in your <build><plugins> section
+=== Running OSGi Blueprint
-[NOTE]
-====
+Use the `camel-karaf-maven-plugin` which is intended for Apache Camel on Karaf/OSGi.
+=== Running CDI
-You may override the default Spring application context file uri
-*META-INF/spring/*.xml* by using the applicationContextUri property in
-the camel-maven-plugin configuration. Paths may be split using a
-semi-colon (;).
+The `camel:run` plugin also supports running a CDI application
-====
+This allows you to boot up any CDI services you wish - whether they are Camel-related, or any other CDI enabled services.
+You should add the CDI container of your choice (e.g. Weld or OpenWebBeans) to the dependencies of the camel-maven-plugin such as in this example.
+
+From the source of Camel you can run a CDI example via
+
+----
+cd examples/camel-example-cdi
+mvn compile camel:run
+----
+
+=== Logging the classpath
+
+You can configure whether the classpath should be logged when `camel:run` executes.
+You can enable this in the configuration using:
[source,xml]
----
@@ -42,47 +65,102 @@ semi-colon (;).
<groupId>org.apache.camel</groupId>
<artifactId>camel-maven-plugin</artifactId>
<configuration>
- <applicationContextUri>META-INF/spring/*.xml;YOUR_FILE_NAME_IN_THE_CLASS_PATH.xml</applicationContextUri>
+ <logClasspath>true</logClasspath>
</configuration>
</plugin>
----
-You can also specify what Main class to use when running the plugin. By
-default this is `org.apache.camel.spring.Main`.
+=== Using live reload of XML files
+
+You can configure the plugin to scan for XML file changes and trigger a reload of the Camel routes which are contained in those XML files.
[source,xml]
----
<plugin>
<groupId>org.apache.camel</groupId>
<artifactId>camel-maven-plugin</artifactId>
- <!-- optional, default value: org.apache.camel.spring.Main -->
<configuration>
- <mainClass>mypackage.boot.camel.CamelStartup</mainClass>
+ <fileWatcherDirectory>src/main/resources/META-INF/spring</fileWatcherDirectory>
</configuration>
</plugin>
----
-== File based spring configuration files
+Then the plugin watches this directory. This allows you to edit the source code from your editor and save the file, and have
+ the running Camel application pickup those changes.
+
+Notice its only changes of Camel routes, eg `<routes>`, or `<route>` which is supported.
+You cannot change Spring or OSGi Blueprint `<bean>` elements.
-From Camel 1.4 onwards loading Spring context files via a file location
-is also supported. You configure this with the
-*fileApplicationContextUri* option. Paths may be split using a
-semi-colon (;). This sort of file location is useful for web application
-projects that store spring configuration files in WEB-INF. It can also
-be used to replace configuration that requires an OSGi container with an
-equivalent non-OSGi configuration.
+
+== camel:prepare-fatjar
+
+The `camel:prepare-fatjar` goal of the Camel Maven Plugin is used to prepare your Camel application
+for being packaged as a _fat jar_. The goal scans the Maven dependencies to discover Camel JARs and
+extract if they have type converters, which gets merged together into a single _uber_ file stored
+in `target/classes/META-INF/services/org/apache/camel/UberTypeConverterLoader`.
+
+This _uber_ loader file contains all the combined type converters the Camel application uses at runtime.
+They are merged together into this single file.
+
+This is needed as otherwise the _fat jar_ maven plugins (such as maven-assembly-plugin, or maven-shade-plugin)
+causes the `TypeConverterLoader` files to be overwritten in the assembled JAR which causes not all type converters
+to be loaded by Camel.
+
+The `UberTypeConverterLoader` ensures they all type converters gets loaded as this file contains all the known
+type converter files.
+
+To use this goal, you can add the following to your Camel application `pom.xml` file:
[source,xml]
----
-<plugin>
- <groupId>org.apache.camel</groupId>
- <artifactId>camel-maven-plugin</artifactId>
- <configuration>
- <fileApplicationContextUri>
- src/main/webapp/WEB-INF/camel*.xml;
- src/test/spring/test-context.xml
- </fileApplicationContextUri>
- </configuration>
-</plugin>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-maven-plugin</artifactId>
+ <version>${camel.version}</version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>prepare-fatjar</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
----
+For example to use this with the `maven-assembly-plugin` you can do as below.
+Remember to specify the class name of *your* main class where it says `com.foo.NameOfMainClass`:
+
+[source,xml]
+----
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-maven-plugin</artifactId>
+ <version>${camel.version}</version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>prepare-fatjar</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <configuration>
+ <archive>
+ <manifest>
+ <mainClass>com.foo.NameOfMainClass</mainClass>
+ </manifest>
+ </archive>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+----
diff --git a/docs/user-manual/modules/ROOT/pages/camel-report-maven-plugin.adoc b/docs/user-manual/modules/ROOT/pages/camel-report-maven-plugin.adoc
index 80d7e4c..8167e8f 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-report-maven-plugin.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-report-maven-plugin.adoc
@@ -135,6 +135,8 @@ The maven plugin *validate* goal supports the following options which can be con
| Parameter | Default Value | Description
| downloadVersion | true | Whether to allow downloading Camel catalog version from the internet. This is needed if the project uses a different Camel version than this plugin is using by default.
| failOnError | false | Whether to fail if invalid Camel endpoints was found. By default the plugin logs the errors at WARN level.
+| coverageThreshold | 100 | The minimum route coverage in percent when using failOnError.
+| overallCoverageThreshold | 0 | The minimum coverage across all routes in percent when using failOnError.
| logUnparseable | false | Whether to log endpoint URIs which was un-parsable and therefore not possible to validate.
| includeJava | true | Whether to include Java files to be validated for invalid Camel endpoints.
| includeXml | true | Whether to include XML files to be validated for invalid Camel endpoints.
@@ -154,7 +156,7 @@ The maven plugin *validate* goal supports the following options which can be con
For example to turn off ignoring usage of deprecated options from the command line, you can run:
----
-$mvn camel-report:validate -Dcamel.ignoreDeprecated=false
+$mvn camel-report:validate -Dcamel.ignoreDeprecated=true
----
Notice that you must prefix the `-D` command argument with `camel.`, eg `camel.ignoreDeprecated` as the option name.
@@ -176,9 +178,23 @@ For generating a report of the coverage of your Camel routes from unit testing.
In the same manner you can generate Java code coverage reports, then this is the same but for Camel routes.
You can therefore use this to know which parts of your Camel routes has been used or not.
+Camel uses JMX to capture metrics during tests which is used for calculating route coverage.
+You must have `camel-management` JAR on the classpath (can be test scoped)
+such as by declaring the following Maven dependency in your pom.xml file:
+
+[source,xml]
+----
+<!-- JMX is needed for route coverage testing -->
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-management</artifactId>
+ <scope>test</scope>
+</dependency>
+----
+
=== Enabling route coverage
-You can enable route coverage while running unit tests either by
+You can enable route coverage while running unit tests either by:
- setting global JVM system property enabling for all test classes
- using `@EnableRouteCoverage` annotation per test class if using `camel-test-spring` module