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/17 07:30:09 UTC
[camel] 02/15: 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 3d6c296100291d00f8247b16551f0e5f9a5186eb
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Mon Aug 16 13:17:00 2021 +0200
Polish and cleanup documentation
---
.../modules/ROOT/pages/spring-xml-extensions.adoc | 182 ++++++++++++--
docs/user-manual/modules/ROOT/pages/spring.adoc | 271 ++-------------------
2 files changed, 175 insertions(+), 278 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/spring-xml-extensions.adoc b/docs/user-manual/modules/ROOT/pages/spring-xml-extensions.adoc
index 65dbd15..4b9a6ba 100644
--- a/docs/user-manual/modules/ROOT/pages/spring-xml-extensions.adoc
+++ b/docs/user-manual/modules/ROOT/pages/spring-xml-extensions.adoc
@@ -1,33 +1,165 @@
-[[SpringXMLExtensions-SpringXMLExtensions]]
-= Spring XML Extensions
+[[SpringXML-SpringXM]]
+= Spring XML
-The Camel Spring XML Extensions allow you use a very concise XML syntax
-to describe your Camel configuration when you are using spring to wire
-together your application.
+Using Camel with Spring XML files, is a classic way, of using XML DSL with Camel.
+Camel has historically been using Spring XML for a long time.
+The Spring framework started with XML files as a popular and common configuration for building Spring applications.
The following is an example of what it looks like:
[source,xml]
----
-<camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/spring">
- <route>
- <from uri="direct:a"/>
- <choice>
- <when>
- <xpath>$foo = 'bar'</xpath>
- <to uri="direct:b"/>
- </when>
- <when>
- <xpath>$foo = 'cheese'</xpath>
- <to uri="direct:c"/>
- </when>
- <otherwise>
- <to uri="direct:d"/>
- </otherwise>
- </choice>
- </route>
-</camelContext>
+<beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ 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
+ ">
+
+ <camelContext xmlns="http://camel.apache.org/schema/spring">
+ <route>
+ <from uri="direct:a"/>
+ <choice>
+ <when>
+ <xpath>$foo = 'bar'</xpath>
+ <to uri="direct:b"/>
+ </when>
+ <when>
+ <xpath>$foo = 'cheese'</xpath>
+ <to uri="direct:c"/>
+ </when>
+ <otherwise>
+ <to uri="direct:d"/>
+ </otherwise>
+ </choice>
+ </route>
+ </camelContext>
+
+</beans>
----
-For more usage examples see the
-xref:{eip-vc}:eips:enterprise-integration-patterns.adoc[Enterprise Integration Patterns].
+== Using Spring XML
+
+You can use Spring XML files to specify Camel routes using XML DSL as shown:
+
+[source,xml]
+--------------------------------------------------------------------------------------------------------------
+<camelContext id="camel-A" xmlns="http://camel.apache.org/schema/spring">
+ <route>
+ <from uri="seda:start"/>
+ <to uri="mock:result"/>
+ </route>
+</camelContext>
+--------------------------------------------------------------------------------------------------------------
+
+=== Configuring Components and Endpoints
+
+You can configure your Component or xref:endpoint.adoc[Endpoint] instances in your Spring XML as follows in this example.
+
+[source,xml]
+--------------------------------------------------------------------------------------------------------------
+<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
+</camelContext>
+
+<bean id="activemq" class="org.apache.camel.component.activemq.ActiveMQComponent">
+ <property name="connectionFactory">
+ <bean class="org.apache.activemq.ActiveMQConnectionFactory">
+ <property name="brokerURL" value="tcp:someserver:61616"/>
+ </bean>
+ </property>
+</bean>
+--------------------------------------------------------------------------------------------------------------
+
+Which allows you to configure a component using any name, but its common to use the same name
+eg (`activemq`). Then you can refer to the component using `activemq:destinationName`.
+
+This works by the Camel lazily fetching components from the Spring context for the scheme name you use for Endpoint xref:uris.adoc[URI]s.
+
+
+
+
+== Using Java DSL with Spring XML files
+
+You can use Java Code to define your xref:route-builder.adoc[RouteBuilder] implementations. These can be defined as beans in spring and then referenced in your camel context e.g.
+
+[source,xml]
+--------------------------------------------------------------------------------------------------------------
+<camelContext xmlns="http://camel.apache.org/schema/spring">
+ <routeBuilder ref="myBuilder" />
+</camelContext>
+
+<bean id="myBuilder" class="org.apache.camel.spring.example.test1.MyRouteBuilder"/>
+--------------------------------------------------------------------------------------------------------------
+
+=== Using package scanning
+
+Camel also provides a powerful feature that allows for the automatic discovery and initialization of routes in given packages. This is configured by adding tags to the camel context in your spring context definition, specifying the packages to be recursively searched for RouteBuilder implementations. To use this feature in 1.X, requires a <package></package> tag specifying a comma separated list of packages that should be searched e.g.
+
+[source,xml]
+--------------------------------------------------------------------------------------------------------------
+<camelContext>
+ <packageScan>
+ <package>com.foo</package>
+ <excludes>**.*Excluded*</excludes>
+ <includes>**.*</includes>
+ </packageScan>
+</camelContext>
+--------------------------------------------------------------------------------------------------------------
+
+This will scan for `RouteBuilder` classes in the _com.foo_ and sub-packages.
+
+You can also filter the classes with includes or excludes such as:
+
+[source,xml]
+--------------------------------------------------------------------------------------------------------------
+<camelContext>
+ <packageScan>
+ <package>com.foo</package>
+ <excludes>**.*Special*</excludes>
+ </packageScan>
+</camelContext>
+--------------------------------------------------------------------------------------------------------------
+
+Which will skip classes that has _Special_ in the name.
+
+Exclude patterns are applied before the include patterns. If no include or exclude patterns are defined then all the Route classes discovered in the packages will be returned.
+
+`?` matches one character `\*` matches zero or more characters `**` matches zero or more segments of a fully qualified name
+
+=== Using context scanning
+
+You can allow Camel to scan the container context, e.g. the Spring ApplicationContext for route builder instances. This allow you to use the Spring *<component-scan>* feature and have Camel pickup any *`RouteBuilder`* instances which was created by Spring in its scan process.
+
+[source,xml]
+--------------------------------------------------------------------------------------------------------------
+<!-- enable Spring @Component scan -->
+<context:component-scan base-package="org.apache.camel.spring.issues.contextscan"/>
+
+<camelContext xmlns="http://camel.apache.org/schema/spring">
+ <!-- and then let Camel use those @Component scanned route builders -->
+ <contextScan/>
+</camelContext>
+--------------------------------------------------------------------------------------------------------------
+
+This allows you to just annotate your routes using the Spring *`@Component`* and have those routes included by Camel:
+
+[source,java]
+--------------------------------------------------------------------------------------------------------------
+@Component
+public class MyRoute extends RouteBuilder {
+
+ @Override
+ public void configure() throws Exception {
+ from("direct:start")
+ .to("mock:result");
+ }
+}
+--------------------------------------------------------------------------------------------------------------
+
+You can also use the ANT style for inclusion and exclusion, as mentioned above in the package scan section.
+
+
+
+== Additional configuration of Spring XML
+
+See more details at xref:advanced-configuration-of-camelcontext-using-spring.adoc[Advanced configuration of CamelContext using Spring].
diff --git a/docs/user-manual/modules/ROOT/pages/spring.adoc b/docs/user-manual/modules/ROOT/pages/spring.adoc
index a474d2b..481e395 100644
--- a/docs/user-manual/modules/ROOT/pages/spring.adoc
+++ b/docs/user-manual/modules/ROOT/pages/spring.adoc
@@ -4,275 +4,40 @@
Apache Camel is designed to work first class with Spring in a number of ways, such as:
* Camel runs on Spring Boot with the Camel Spring Boot project
-* Camel works with Spring XML configuration files (classic Spring XML)
+* Camel works with Spring XML files (classic Spring XML)
* Camel works with Spring dependency injection
* Camel works with Spring configuration and property placeholders
* Camel works with Spring transactions
* Camel works with Spring testing
-== Using Spring to configure the CamelContext
+== Using Camel on Spring Boot
-You can configure a CamelContext inside any spring.xml using the CamelContextFactoryBean. This will automatically start the CamelContext along with any referenced Routes along any referenced Component and Endpoint instances.
+See the xref:/camel-spring-boot/latest/[Camel Spring Boot] project.
-* Adding Camel schema
-* Configure Routes in two ways:
-** Using Java Code
-** Using Spring XML
+== Using Camel with Spring XML files
-[[Spring-AddingCamelSchema]]
-== Adding Camel Schema
-For Camel 1.x you need to use the following namespace:
-....
-http://activemq.apache.org/camel/schema/spring
-....
+Using Camel with Spring XML files, is a classic way, of using XML DSL with Camel.
+Camel has historically been using Spring XML for a long time. The Spring framework
+started with XML files as a popular and common configuration for building Spring applications.
-with the following schema location:
-....
-http://activemq.apache.org/camel/schema/spring/camel-spring.xsd
-....
+To use Camel with Spring XML files see the xref:spring-xml-extensions.adoc[Spring XML] documentation.
-You need to add Camel to the schemaLocation declaration
-....
-http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
-....
+== Using Spring dependency injection
-So the XML file looks like this:
+Spring dependency injection is integrated first-class when using Spring and Spring together.
-[source,xml]
---------------------------------------------------------------------------------------------------------------
-<beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- 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
- ">
---------------------------------------------------------------------------------------------------------------
+For example when using Camel on Spring Boot, then you can use any kind of Spring dependency and
+be able to inject Camel resources such as 'CamelContext', xref:endpoint.adoc[Endpoint] and many more.
-== Using `camel:` Namespace
-Or you can refer to the camel XSD in the XML declaration:
-....
-xmlns:camel="http://camel.apache.org/schema/spring"
-....
+== Using Camel with Spring configuration and property placeholders
-... so the declaration is:
-....
-xsi:schemaLocation="
-http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
-....
-[source,xml]
---------------------------------------------------------------------------------------------------------------
-<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">
+See xref:using-propertyplaceholder.adoc[Using Property Placeholder] documentation.
---------------------------------------------------------------------------------------------------------------
+== Using Camel with Spring transactions
-... and then use the camel: namespace prefix, and you can omit the inline namespace declaration:
-[source,xml]
---------------------------------------------------------------------------------------------------------------
- <camel:camelContext id="camel5">
- <camel:package>org.apache.camel.spring.example</camel:package>
- </camel:camelContext>
---------------------------------------------------------------------------------------------------------------
+See xref:{eip-vc}:eips:transactional-client.adoc[Transactional Client]} EIP.
-== Advanced Configuration Using Spring
-See more details at Advanced configuration of CamelContext using Spring
+== Using Camel with Spring testing
-== Using Java Code
-You can use Java Code to define your xref:route-builder.adoc[RouteBuilder] implementations. These can be defined as beans in spring and then referenced in your camel context e.g.
-[source,xml]
---------------------------------------------------------------------------------------------------------------
-<camelContext id="camel5" xmlns="http://camel.apache.org/schema/spring">
- <routeBuilder ref="myBuilder" />
-</camelContext>
-<bean id="myBuilder" class="org.apache.camel.spring.example.test1.MyRouteBuilder"/>
---------------------------------------------------------------------------------------------------------------
-
-== Using <package>
-Camel also provides a powerful feature that allows for the automatic discovery and initialization of routes in given packages. This is configured by adding tags to the camel context in your spring context definition, specifying the packages to be recursively searched for RouteBuilder implementations. To use this feature in 1.X, requires a <package></package> tag specifying a comma separated list of packages that should be searched e.g.
-
-[source,xml]
---------------------------------------------------------------------------------------------------------------
-<camel:camelContext id="camel5">
- <camel:package>org.apache.camel.spring.example</camel:package>
-</camel:camelContext>
---------------------------------------------------------------------------------------------------------------
-Use caution when specifying the package name as org.apache.camel or a sub package of this. This causes Camel to search in its own packages for your routes which could cause problems.
-
-Will ignore already instantiated classes
-
-The *`<package>`* and *`<packageScan>`* will skip any classes which has already been created by Spring etc. So if you define a route builder as a spring bean tag then that class will be skipped. You can include those beans using *`<routeBuilder ref="theBeanId"/>`* or the *`<contextScan>`* feature.
-
-== Using `<packageScan>`
-
-In Camel 2.0 this has been extended to allow selective inclusion and exclusion of discovered route classes using Ant like path matching. In spring this is specified by adding a *`<packageScan/>`* tag. The tag must contain one or more *`package`* elements (similar to *`1.x`*), and optionally one or more *`includes`* or *`excludes`* elements specifying patterns to be applied to the fully qualified names of the discovered classes. e.g.,
-
-[source,xml]
---------------------------------------------------------------------------------------------------------------
-<camelContext xmlns="http://camel.apache.org/schema/spring">
- <packageScan>
- <package>org.example.routes</package>
- <excludes>**.*Excluded*</excludes>
- <includes>**.*</includes>
- </packageScan>
-</camelContext>
---------------------------------------------------------------------------------------------------------------
-
-Exclude patterns are applied before the include patterns. If no include or exclude patterns are defined then all the Route classes discovered in the packages will be returned.
-
-In the above example, camel will scan all the *`org.example.routes`* package and any subpackages for *`RouteBuilder`* classes. Say the scan finds two *`RouteBuilders`*, one in *`org.example.routes`* called *`MyRoute`* and another *`MyExcludedRoute`* in a subpackage *`excluded`*. The fully qualified names of each of the classes are extracted (*`org.example.routes.MyRoute`*, *`org.example.routes.excluded.MyExcludedRoute`*) and the include and exclude patterns are applied.
-
-The exclude pattern *`**.*Excluded*`* is going to match the FQCN *`org.example.routes.excluded.MyExcludedRoute`* and veto camel from initializing it.
-
-Under the covers, this is using Spring's http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/util/AntPathMatcher.html[AntPatternMatcher] implementation, which matches as follows
-
-? matches one character * matches zero or more characters ** matches zero or more segments of a fully qualified name
-
-For example:
-
-*`**.*Excluded*`* would match
-*`org.simple.Excluded`*, *`org.apache.camel.SomeExcludedRoute`* or
-*`org.example.RouteWhichIsExcluded`*.
-
-*`**.??cluded*`* would match
-*`org.simple.IncludedRoute`*, *`org.simple.Excluded`* but _not_ match
-*`org.simple.PrecludedRoute`*.
-
-== Using `contextScan`
-
-*Since Camel 2.4*
-
-You can allow Camel to scan the container context, e.g. the Spring ApplicationContext for route builder instances. This allow you to use the Spring *<component-scan>* feature and have Camel pickup any *`RouteBuilder`* instances which was created by Spring in its scan process.
-
-[source,xml]
---------------------------------------------------------------------------------------------------------------
-<!-- enable Spring @Component scan -->
-<context:component-scan base-package="org.apache.camel.spring.issues.contextscan"/>
-
-<camelContext xmlns="http://camel.apache.org/schema/spring">
- <!-- and then let Camel use those @Component scanned route builders -->
- <contextScan/>
-</camelContext>
---------------------------------------------------------------------------------------------------------------
-
-This allows you to just annotate your routes using the Spring *`@Component`* and have those routes included by Camel:
-[source,java]
---------------------------------------------------------------------------------------------------------------
-@Component
-public class MyRoute extends SpringRouteBuilder {
- @Override public void configure() throws Exception {
- from("direct:start") .to("mock:result");
- }
-}
-
---------------------------------------------------------------------------------------------------------------
-
-
-You can also use the ANT style for inclusion and exclusion, as mentioned above in the *`<packageScan>`* documentation.
-
-how do i import routes from other xml files
-
-== Test Time Exclusion.
-At test time it is often desirable to be able to selectively exclude matching routes from being initialized that are not applicable or useful to the test scenario. For instance you might a spring context file *`routes-context.xml`* and three Route builders **`RouteA`, **`RouteB` and *`RouteC`* in the *`org.example.routes`* package. The *`packageScan`* definition would discover all three of these routes and initialize them.
-
-Say *`RouteC`* is not applicable to our test scenario and generates a lot of noise during test. It would be nice to be able to exclude this route from this specific test. The *`SpringTestSupport`* class has been modified to allow this. It provides two methods (*`excludedRoute`* and *`excludedRoutes`*) that may be overridden to exclude a single class or an array of classes.
-
-[source,java]
---------------------------------------------------------------------------------------------------------------
-public class RouteAandRouteBOnlyTest extends SpringTestSupport {
- @Override
- protected Class excludeRoute() {
- return RouteC.class;
- }
-}
---------------------------------------------------------------------------------------------------------------
-
-In order to hook into the *`camelContext`* initialization by spring to exclude the *`MyExcludedRouteBuilder.class`* we need to intercept the spring context creation. When overriding *`createApplicationContext`* to create the spring context, we call the *`getRouteExcludingApplicationContext()`* method to provide a special parent spring context that takes care of the exclusion.
-
-[source,java]
---------------------------------------------------------------------------------------------------------------
-@Override
-protected AbstractXmlApplicationContext createApplicationContext() {
- return new ClassPathXmlApplicationContext(
- new String[] {"routes-context.xml"}, getRouteExcludingApplicationContext());
-}
---------------------------------------------------------------------------------------------------------------
-
-*`RouteC`* will now be excluded from initialization. Similarly, in another test that is testing only *`RouteC`*, we could exclude *`RouteB`* and *`RouteA`* by overriding:
-
-[source,java]
---------------------------------------------------------------------------------------------------------------
-@Override
-protected Class[] excludeRoutes() {
- return new Class[]{RouteA.class, RouteB.class};
-}
---------------------------------------------------------------------------------------------------------------
-
-
-== Using Spring XML
-You can use Spring 2.0 XML configuration to specify your XML Configuration for xref:routes.adoc[Routes] such as in the following http://svn.apache.org/repos/asf/camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/routingUsingCamelContextFactory.xml[example].
-[source,xml]
---------------------------------------------------------------------------------------------------------------
-<camelContext id="camel-A" xmlns="http://camel.apache.org/schema/spring">
- <route>
- <from uri="seda:start"/>
- <to uri="mock:result"/>
- </route>
-</camelContext>
---------------------------------------------------------------------------------------------------------------
-
-Configuring Components and Endpoints
-
-You can configure your Component or xref:endpoint.adoc[Endpoint] instances in your Spring XML as follows in this example.
-[source,xml]
---------------------------------------------------------------------------------------------------------------
-<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
- <jmxAgent id="agent" disabled="true"/>
-</camelContext>
-
-<bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent">
- <property name="connectionFactory">
- <bean class="org.apache.activemq.ActiveMQConnectionFactory">
- <property name="brokerURL" value="vm://localhost?broker.persistent=false&broker.useJmx=false"/>
- </bean>
- </property>
-</bean>
---------------------------------------------------------------------------------------------------------------
-
-Which allows you to configure a component using some name (*`activemq`* in the above example), then you can refer to the component using *`activemq:[queue:|topic:]destinationName`* This works by the SpringCamelContext lazily fetching components from the spring context for the scheme name you use for Endpoint URIs.
-
-For more detail see Configuring Endpoints and Components.
-
-== Spring Cache Idempotent Repository
-
-Available as of *Camel 2.17.1*
-
-[source,xml]
---------------------------------------------------------------------------------------------------------------
-<bean id="repo" class="org.apache.camel.spring.processor.idempotent.SpringCacheIdempotentRepository">
- <constructor-arg>
- <bean class="org.springframework.cache.guava.GuavaCacheManager"/>
-</constructor-arg>
- <constructor-arg value="idempotent"/>
-</bean>
-<camelContext xmlns="http://camel.apache.org/schema/spring">
- <route id="idempotent-cache">
- <from uri="direct:start" />
- <idempotentConsumer messageIdRepositoryRef="repo" skipDuplicate="true">
- <header>MessageId</header>
- <to uri="log:org.apache.camel.spring.processor.idempotent?level=INFO&showAll=true&multiline=true" /> <to uri="mock:result"/>
- </idempotentConsumer>
- </route>
-</camelContext>
---------------------------------------------------------------------------------------------------------------
-
-CamelContextAware
-If you want to be injected with the xref:camelcontext.adoc[CamelContext] in your POJO just implement the https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/CamelContextAware.html[CamelContextAware interface]; then when Spring creates your POJO the CamelContext will be injected into your POJO. Also see the Bean Integration for further injections.
-
-== Integration Testing
-
-To avoid a hung route when testing using Spring Transactions see the note about Spring Integration Testing under Transactional Client.
+See xref:spring-testing.adoc[Spring testing] documentation.