This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 790cc20914228f909789ac03a3874533c89f39df
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Mon Jun 17 13:33:22 2019 +0200
CAMEL-13647: Allow to do autowrire by classpath.
---
.../src/main/docs/camel-main-maven-plugin.adoc | 123 +++++++++++++++++++++
1 file changed, 123 insertions(+)
diff --git
a/catalog/camel-main-maven-plugin/src/main/docs/camel-main-maven-plugin.adoc
b/catalog/camel-main-maven-plugin/src/main/docs/camel-main-maven-plugin.adoc
index 912ac3e..99ca864 100644
--- a/catalog/camel-main-maven-plugin/src/main/docs/camel-main-maven-plugin.adoc
+++ b/catalog/camel-main-maven-plugin/src/main/docs/camel-main-maven-plugin.adoc
@@ -7,6 +7,18 @@ The Camel Main Maven Plugin supports the following goals
== camel:autowire
To pre-scan your project and prepare autowiring by classpath scanning.
+The idea is to use this maven plugin at build/compile time and detect what's
on the classpath
+and preconfigure some convention over configurations for using Camel Main with
configuration.
+
+This is done by checking which Camel components are available on the classpath,
+and check if they have any component options that are complex objects (not
string, number, booleans etc)
+and is an interface, which can be autowired from an implementation class that
+are also available on the classpath.
+
+A classic example is to setup JMS `ConnectionFactory` on the JMS component to
which
+JMS client you are using. Another example is JDBC drivers etc. In other words
+its a bit like Spring Boot _starter_ JARs that also offers a similar concept,
but
+without the phase of doing this during build time.
----
mvn camel-main:autowire
@@ -33,3 +45,114 @@ You can also enable the plugin to automatic run as part of
the build to catch th
The phase determines when the plugin runs. In the sample above the phase is
`process-classes` which runs after
the compilation of the main source code.
+
+=== Include and Exclude properties or components
+
+By default the `autowire` goal will scan all the detected Camel components
from the classpath.
+
+For example as shown below, there are 29 detected Camel components,
+and 1 mapping was created in the `autowire.properties` file
+
+[source,text]
+----
+[INFO] --- camel-main-maven-plugin:3.0.0-SNAPSHOT:autowire (generate) @
camel-example-main-artemis ---
+[INFO] Detected Camel version used in project: 3.0.0-SNAPSHOT
+[INFO] Pre-scanning using Camel version: 3.0.0-SNAPSHOT
+[INFO] Discovered 29 Camel components from classpath: [bean, browse, class,
controlbus, dataformat, dataset, dataset-test, direct, direct-vm, file, jms,
language, log, mock, properties, quartz, quartz2, ref, rest, rest-api, saga,
scheduler, seda, spring-event, stub, timer, validator, vm, xslt]
+[INFO] Created file:
/Users/davsclaus/workspace/camel/examples/camel-example-main-artemis/target/classes/META-INF/services/org/apache/camel/autowire.properties
(autowire by classpath: 1)
+----
+
+You can use exclude and include patterns to specify which properties and/or
components to use.
+
+For example to only include the JMS component you can do:
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-main-maven-plugin</artifactId>
+ <configuration>
+ <logClasspath>false</logClasspath>
+ <!-- just include only the jms component -->
+ <include>jms</include>
+ </configuration>
+ <executions>
+ <execution>
+ <phase>process-classes</phase>
+ <goals>
+ <goal>autowire</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+----
+
+For more advanced patterns you can use wildcards and regular expressions, for
example to only include JMS or AMQP components:
+[source,xml]
+----
+<include>(jms|amqp)</include>
+----
+
+You can also work with property names, for example to only configure
`ConnectionFactory` you can do:
+[source,xml]
+----
+<include>connection-factory</include>
+----
+
+You can also specify which Camel component this would apply, such as the JMS
component:
+[source,xml]
+----
+<include>camel.component.jms.connection-factory</include>
+----
+
+NOTE: If you use excludes then they take precedence over include.
+
+=== Mappings
+
+Mappings are used for more complex mappings where you can specify the class
type of the property value.
+For example one of the default mappings is as shown:
+[source,properties]
+----
+javax.jms.ConnectionFactory=org.apache.activemq.artemis.jms.client.ActiveMQJMSConnectionFactory;org.apache.activemq.ActiveMQConnectionFactory
+----
+
+This tells the `autowire` goal that if the value of the property is a
`javax.jms.ConnectionFactory` type
+then we should only accept the following implementations when scanning the
classpath:
+
+- `org.apache.activemq.artemis.jms.client.ActiveMQJMSConnectionFactory`
+- `org.apache.activemq.ActiveMQConnectionFactory`
+
+This means when there for example are 8 implementations in the classpath for
`javax.jms.ConnectionFactory` then
+this mapping will select the on of the 2 above if they are on the classpath in
the given prioritized order.
+
+This allows us to have convention over configuration and just drop either the
Apache Artemis JMS client or Apache ActiveMQ JMS client
+on the classpath, and the Camel JMS component will automatic be configured to
use their `ConnectionFactory` classes.
+
+You can also specify the skip certain types, such as
+
+[source,properties]
+----
+org.springframework.jms.core.JmsOperations=#skip#
+----
+
+Which means the `autowire` goal skips any property values that are of type
`org.springframework.jms.core.JmsOperations`.
+
+=== Options
+
+The maven plugin *autowire* 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
+| logClasspath | false | Whether to log the classpath when starting
+| 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.
+| exclude | | To exclude autowiring specific properties with these key names.
You can also configure a single entry and separate the excludes with comma.
+| include | | To include autowiring specific properties with these key names.
You can also configure a single entry and separate the includes with comma.
+| mappings | | To setup special mappings between known types as key=value
pairs. You can also configure a single entry and separate the mappings with
comma.
+| mappingsFile | | Optional mappings file loaded from classpath, with mapping
that override any default mappings. Will by default load the file
`camel-main-mappings.properties` from the classpath root.
+|===
+
+==== Examples
+
+You can find more details and a working example at
`examples/camel-example-main-artemis`.
+
