Skip to content

Commit 489d2ae

Browse files
committed
CAMEL-16861: Update docs
1 parent 1e85c97 commit 489d2ae

4 files changed

Lines changed: 81 additions & 68 deletions

File tree

docs/user-manual/modules/ROOT/pages/spring-xml-extensions.adoc

Lines changed: 47 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
= Spring XML
22

33
Using Camel with Spring XML files, is a classic way, of using XML DSL with Camel.
4+
45
Camel has historically been using Spring XML for a long time.
56
The Spring framework started with XML files as a popular and common configuration for building Spring applications.
67

78
The following is an example of what it looks like:
89

10+
.Spring XML Classic
911
[source,xml]
1012
----
1113
<beans xmlns="http://www.springframework.org/schema/beans"
@@ -41,45 +43,65 @@ The following is an example of what it looks like:
4143

4244
The following dependency needs to be added to your pom.xml so that Spring XML files can be scanned by Camel:
4345

46+
[tabs]
47+
====
48+
49+
Standalone::
50+
+
4451
[source,xml]
45-
--------------------------------------------------------------------------------------------------------------
52+
----
53+
<dependency>
54+
<groupId>org.apache.camel</groupId>
55+
<artifactId>camel-spring-xml</artifactId>
56+
</dependency>
57+
----
58+
59+
Spring Boot::
60+
+
61+
[source,xml]
62+
----
4663
<dependency>
4764
<groupId>org.apache.camel.springboot</groupId>
4865
<artifactId>camel-spring-boot-xml-starter</artifactId>
4966
</dependency>
50-
--------------------------------------------------------------------------------------------------------------
67+
----
68+
====
5169

5270
You can use Spring XML files to specify Camel routes using XML DSL as shown:
5371

5472
[source,xml]
55-
--------------------------------------------------------------------------------------------------------------
73+
----
5674
<camelContext id="camel-A" xmlns="http://camel.apache.org/schema/spring">
5775
<route>
5876
<from uri="seda:start"/>
5977
<to uri="mock:result"/>
6078
</route>
6179
</camelContext>
62-
--------------------------------------------------------------------------------------------------------------
80+
----
6381

6482
=== Configuring Components and Endpoints
6583

6684
You can configure your Component or xref:endpoint.adoc[Endpoint] instances in your Spring XML as follows in this example.
6785

6886
[source,xml]
69-
--------------------------------------------------------------------------------------------------------------
70-
<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
71-
</camelContext>
72-
87+
----
7388
<bean id="activemq" class="org.apache.camel.component.activemq.ActiveMQComponent">
7489
<property name="connectionFactory">
7590
<bean class="org.apache.activemq.ActiveMQConnectionFactory">
7691
<property name="brokerURL" value="tcp:someserver:61616"/>
7792
</bean>
7893
</property>
7994
</bean>
80-
--------------------------------------------------------------------------------------------------------------
8195
82-
Which allows you to configure a component using any name, but its common to use the same name
96+
<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
97+
<route>
98+
<from uri="activemq:cheese"/>
99+
<to uri="log:cheese"/>
100+
</route>
101+
</camelContext>
102+
----
103+
104+
Which allows you to configure a component using any name, but it's common to use the same name
83105
eg (`activemq`). Then you can refer to the component using `activemq:destinationName`.
84106

85107
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.
@@ -89,42 +111,40 @@ This works by the Camel lazily fetching components from the Spring context for t
89111
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.
90112

91113
[source,xml]
92-
--------------------------------------------------------------------------------------------------------------
114+
----
115+
<bean id="myBuilder" class="com.foo.MyRouteBuilder"/>
116+
93117
<camelContext xmlns="http://camel.apache.org/schema/spring">
94118
<routeBuilder ref="myBuilder"/>
95119
</camelContext>
96-
97-
<bean id="myBuilder" class="org.apache.camel.spring.example.test1.MyRouteBuilder"/>
98-
--------------------------------------------------------------------------------------------------------------
120+
----
99121

100122
=== Using package scanning
101123

102124
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.
103125

104126
[source,xml]
105-
--------------------------------------------------------------------------------------------------------------
127+
----
106128
<camelContext>
107129
<packageScan>
108130
<package>com.foo</package>
109-
<excludes>**.*Excluded*</excludes>
110-
<includes>**.*</includes>
111131
</packageScan>
112132
</camelContext>
113-
--------------------------------------------------------------------------------------------------------------
133+
----
114134

115135
This will scan for `RouteBuilder` classes in the _com.foo_ and sub-packages.
116136

117137
You can also filter the classes with includes or excludes such as:
118138

119139
[source,xml]
120-
--------------------------------------------------------------------------------------------------------------
140+
----
121141
<camelContext>
122142
<packageScan>
123143
<package>com.foo</package>
124144
<excludes>**.*Special*</excludes>
125145
</packageScan>
126146
</camelContext>
127-
--------------------------------------------------------------------------------------------------------------
147+
----
128148

129149
Which will skip classes that has _Special_ in the name.
130150

@@ -137,20 +157,20 @@ Exclude patterns are applied before the include patterns. If no include or exclu
137157
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.
138158

139159
[source,xml]
140-
--------------------------------------------------------------------------------------------------------------
160+
----
141161
<!-- enable Spring @Component scan -->
142162
<context:component-scan base-package="org.apache.camel.spring.issues.contextscan"/>
143163
144164
<camelContext xmlns="http://camel.apache.org/schema/spring">
145165
<!-- and then let Camel use those @Component scanned route builders -->
146166
<contextScan/>
147167
</camelContext>
148-
--------------------------------------------------------------------------------------------------------------
168+
----
149169

150170
This allows you to just annotate your routes using the Spring *`@Component`* and have those routes included by Camel:
151171

152172
[source,java]
153-
--------------------------------------------------------------------------------------------------------------
173+
----
154174
@Component
155175
public class MyRoute extends RouteBuilder {
156176
@@ -160,10 +180,12 @@ public class MyRoute extends RouteBuilder {
160180
.to("mock:result");
161181
}
162182
}
163-
--------------------------------------------------------------------------------------------------------------
183+
----
164184

165185
You can also use the ANT style for inclusion and exclusion, as mentioned above in the package scan section.
166186

167187
== Additional configuration of Spring XML
168188

169-
See more details at xref:advanced-configuration-of-camelcontext-using-spring.adoc[Camel Spring XML Auto Configuration].
189+
See more details at xref:advanced-configuration-of-camelcontext-using-spring.adoc[Camel Spring XML Auto Configuration]
190+
and https://github.com/apache/camel-spring-boot-examples/tree/main/xml-import[Spring Boot classic XML] example.
191+

docs/user-manual/modules/ROOT/pages/spring.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ To use Camel with Spring XML files see the xref:spring-xml-extensions.adoc[Sprin
2323

2424
== Using Spring dependency injection
2525

26-
Spring dependency injection is integrated first-class when using Spring and Spring together.
26+
Spring dependency injection is integrated first-class when using Camel and Spring together.
2727

2828
For example when using Camel on Spring Boot, then you can use any kind of Spring dependency and
2929
be able to inject Camel resources such as 'CamelContext', xref:endpoint.adoc[Endpoint] and many more.
@@ -38,5 +38,5 @@ See xref:components:eips:transactional-client.adoc[Transactional Client] EIP.
3838

3939
== Using Camel with Spring testing
4040

41-
See xref:components:others:test-spring-junit5.adoc[camel-test-spring-junit5] documentation.
41+
See xref:components:others:test-spring-junit5.adoc[camel-test-spring-junit5] and xref:components:others:test-spring-junit6.adoc[camel-test-spring-junit6] documentation.
4242

docs/user-manual/modules/ROOT/pages/startup-condition.adoc

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,4 +37,3 @@ Or to use a custom condition by its class name:
3737
camel.startupcondition.enabled = true
3838
camel.startupcondition.customClassNames = com.foo.MyStartupCondition
3939
----
40-

docs/user-manual/modules/ROOT/pages/stream-caching.adoc

Lines changed: 32 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -31,47 +31,23 @@ Stream caching is configured using `org.apache.camel.spi.StreamCachingStrategy`.
3131

3232
The strategy has the following options:
3333

34-
[width="100%",cols="20%,20%,60%",options="header"]
35-
|=======================================================================
34+
[width="100%",cols="1m,1,4",options="header"]
35+
|===
3636
| Option | Default | Description
37-
38-
| enabled | true
39-
| Whether stream caching is enabled
40-
4137
| allowClasses | | To filter stream caching of a given set of allowed/denied classes. By default, all classes that are `java.io.InputStream` is allowed. Multiple class names can be separated by comma.
42-
38+
| anySpoolRules | false | Whether any or all ``SpoolRule``s must return `true` to determine if the stream should be spooled or not. This can be used as applying AND/OR binary logic to all the rules. By default it's AND based.
39+
| bufferSize | 4096 | Sets the buffer size to use when allocating in-memory buffers used for in-memory stream caches.
4340
| denyClasses | | To filter stream caching of a given set of allowed/denied classes. By default, all classes that are `java.io.InputStream` is allowed. Multiple class names can be separated by comma.
44-
45-
| spoolEnabled | false
46-
| Whether spool to disk is enabled
47-
48-
| spoolDirectory | ${java.io.tmpdir}/camel/camel-tmp-\#uuid#
49-
| Base directory where temporary files for spooled streams should be stored. This option supports naming patterns as documented below.
50-
51-
| spoolCipher | null
52-
| If set, the temporary files are encrypted using the specified cipher transformation (i.e., a valid stream or 8-bit cipher name such as "RC4", "AES/CTR/NoPadding". An empty name "" is treated as null).
53-
54-
| spoolThreshold | 128 KB
55-
| Size in bytes when the stream should be spooled to disk instead of keeping in memory. Use a value of 0 or negative to disable it all together so streams is always kept in memory regardless of their size.
56-
57-
| spoolUsedHeapMemoryThreshold | 0
58-
| A percentage (1 to 99) of current used heap memory to use as threshold for spooling streams to disk. The upper bounds is based on heap committed (guaranteed memory the JVM can claim). This can be used to spool to disk when running low on memory.
59-
60-
| spoolUsedHeapMemoryLimit | Max
61-
| If `spoolUsedHeapMemoryThreshold` is in use, then whether the used heap memory upper limit is either Max or Committed.
62-
63-
| anySpoolRules | false
64-
| Whether any or all ``SpoolRule``s must return `true` to determine if the stream should be spooled or not. This can be used as applying AND/OR binary logic to all the rules. By default it's AND based.
65-
66-
| bufferSize | 4096
67-
| Sets the buffer size to use when allocating in-memory buffers used for in-memory stream caches.
68-
69-
| removeSpoolDirectoryWhenStopping | true
70-
| Whether to remove the spool directory when stopping xref:camelcontext.adoc[CamelContext].
71-
72-
| statisticsEnabled | false
73-
| Whether utilization statistics is enabled. By enabling this you can see these statics for example with JMX.
74-
|=======================================================================
41+
| enabled | true | Whether stream caching is enabled
42+
| removeSpoolDirectoryWhenStopping | true | Whether to remove the spool directory when stopping xref:camelcontext.adoc[CamelContext].
43+
| spoolCipher | null | If set, the temporary files are encrypted using the specified cipher transformation (i.e., a valid stream or 8-bit cipher name such as "RC4", "AES/CTR/NoPadding". An empty name "" is treated as null).
44+
| spoolDirectory | ${java.io.tmpdir}/camel/camel-tmp-\#uuid# | Base directory where temporary files for spooled streams should be stored. This option supports naming patterns as documented below.
45+
| spoolEnabled | false | Whether spool to disk is enabled
46+
| spoolThreshold | 128 KB | Size in bytes when the stream should be spooled to disk instead of keeping in memory. Use a value of 0 or negative to disable it all together so streams is always kept in memory regardless of their size.
47+
| spoolUsedHeapMemoryLimit | Max | If `spoolUsedHeapMemoryThreshold` is in use, then whether the used heap memory upper limit is either Max or Committed.
48+
| spoolUsedHeapMemoryThreshold | 0 | A percentage (1 to 99) of current used heap memory to use as threshold for spooling streams to disk. The upper bounds is based on heap committed (guaranteed memory the JVM can claim). This can be used to spool to disk when running low on memory.
49+
| statisticsEnabled | false | Whether utilization statistics is enabled. By enabling this you can see these statics for example with JMX.
50+
|===
7551

7652
=== SpoolDirectory naming pattern
7753

@@ -133,9 +109,25 @@ from("file:inbox")
133109
.to("bean:foo");
134110
----
135111

136-
== Configuring StreamCachingStrategy in XML
112+
== Configuring Stream Caching using Application Properties
113+
114+
When using Spring Boot, Quarkus or Camel Standalone It's recommended to configure stream caching in the `application.properties` configuration file:
115+
116+
.Application Properties
117+
[source,properties]
118+
----
119+
camel.main.streamCachingSpoolEnabled = true
120+
camel.main.streamCachingSpoolDirectory = /tmp/cachedir
121+
camel.main.streamCachingSpoolThreshold = 65536
122+
camel.main.streamCachingBufferSize = 16384;
123+
----
124+
125+
TIP: You can run Camel JBang: `camel doc main --filter=stream` from CLI to see all the options.
126+
127+
128+
== Configuring StreamCachingStrategy in Spring XML
137129

138-
In XML you can enable stream caching on the `<camelContext>` and then do the configuration in the `streamCaching` element:
130+
In xref:spring-xml-extensions.adoc[Spring XML] you can enable stream caching on the `<camelContext>` and then do the configuration in the `streamCaching` element:
139131

140132
[source,xml]
141133
----

0 commit comments

Comments
 (0)