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:10 UTC
[camel] 03/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 757aa584203a4a29d43b1246cfd974403a5a8d68
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Mon Aug 16 16:44:18 2021 +0200
Polish and cleanup documentation
---
.../apache/camel/catalog/docs/sql-component.adoc | 4 +-
.../camel-sql/src/main/docs/sql-component.adoc | 4 +-
.../docs/modules/eips/pages/content-enricher.adoc | 2 +-
.../modules/eips/pages/message-translator.adoc | 2 +-
.../modules/ROOT/pages/sql-component.adoc | 4 +-
docs/user-manual/modules/ROOT/nav.adoc | 1 -
.../modules/ROOT/pages/stream-caching.adoc | 243 +++------------------
.../user-manual/modules/ROOT/pages/templating.adoc | 50 -----
8 files changed, 34 insertions(+), 276 deletions(-)
diff --git a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sql-component.adoc b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sql-component.adoc
index bb7505c..54a887b 100644
--- a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sql-component.adoc
+++ b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/sql-component.adoc
@@ -260,8 +260,8 @@ You can use the option `useMessageBodyForSql` that
allows to use the message body as the SQL statement, and then the SQL
parameters must be provided in a header with the
key `SqlConstants.SQL_PARAMETERS`. This allows the SQL component to work
-more dynamically as the SQL query is from the message body. Use
-xref:manual::templating.adoc[Camel templating]
+more dynamically as the SQL query is from the message body. Use templating
+(such as xref:components::velocity-component.adoc[Velocity], xref:components::freemarker-component.adoc[Freemarker])
for conditional processing, e.g. to include or exclude `where` clauses
depending on the presence of query parameters.
diff --git a/components/camel-sql/src/main/docs/sql-component.adoc b/components/camel-sql/src/main/docs/sql-component.adoc
index bb7505c..54a887b 100644
--- a/components/camel-sql/src/main/docs/sql-component.adoc
+++ b/components/camel-sql/src/main/docs/sql-component.adoc
@@ -260,8 +260,8 @@ You can use the option `useMessageBodyForSql` that
allows to use the message body as the SQL statement, and then the SQL
parameters must be provided in a header with the
key `SqlConstants.SQL_PARAMETERS`. This allows the SQL component to work
-more dynamically as the SQL query is from the message body. Use
-xref:manual::templating.adoc[Camel templating]
+more dynamically as the SQL query is from the message body. Use templating
+(such as xref:components::velocity-component.adoc[Velocity], xref:components::freemarker-component.adoc[Freemarker])
for conditional processing, e.g. to include or exclude `where` clauses
depending on the presence of query parameters.
diff --git a/core/camel-core-engine/src/main/docs/modules/eips/pages/content-enricher.adoc b/core/camel-core-engine/src/main/docs/modules/eips/pages/content-enricher.adoc
index 4468a91..a257f19 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/content-enricher.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/content-enricher.adoc
@@ -14,7 +14,7 @@ image::eip/DataEnricher.gif[image]
[[ContentEnricher-ContentenrichmentusingaMessageTranslatororaProcessor]]
== Content enrichment using a Message Translator or a Processor
-You can use xref:latest@manual:ROOT:templating.adoc[Templating] to consume a message from
+You can consume a message from
one destination, transform it with something like
xref:components::velocity-component.adoc[Velocity] or xref:components::xquery-component.adoc[XQuery], and then send
it on to another destination. For example using InOnly (one way
diff --git a/core/camel-core-engine/src/main/docs/modules/eips/pages/message-translator.adoc b/core/camel-core-engine/src/main/docs/modules/eips/pages/message-translator.adoc
index 4974569..7dcf17a 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/message-translator.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/message-translator.adoc
@@ -52,7 +52,7 @@ invoke a bean
</route>
----
-You can also use xref:latest@manual:ROOT:templating.adoc[Templating] to consume a message
+You can also consume a message
from one destination, transform it with something like
xref:components::velocity-component.adoc[Velocity] or xref:components::xquery-component.adoc[XQuery] and then send
it on to another destination. For example using InOnly (one way
diff --git a/docs/components/modules/ROOT/pages/sql-component.adoc b/docs/components/modules/ROOT/pages/sql-component.adoc
index e02e8c8..ff9400a 100644
--- a/docs/components/modules/ROOT/pages/sql-component.adoc
+++ b/docs/components/modules/ROOT/pages/sql-component.adoc
@@ -262,8 +262,8 @@ You can use the option `useMessageBodyForSql` that
allows to use the message body as the SQL statement, and then the SQL
parameters must be provided in a header with the
key `SqlConstants.SQL_PARAMETERS`. This allows the SQL component to work
-more dynamically as the SQL query is from the message body. Use
-xref:manual::templating.adoc[Camel templating]
+more dynamically as the SQL query is from the message body. Use templating
+(such as xref:components::velocity-component.adoc[Velocity], xref:components::freemarker-component.adoc[Freemarker])
for conditional processing, e.g. to include or exclude `where` clauses
depending on the presence of query parameters.
diff --git a/docs/user-manual/modules/ROOT/nav.adoc b/docs/user-manual/modules/ROOT/nav.adoc
index af14584..2cad1a5 100644
--- a/docs/user-manual/modules/ROOT/nav.adoc
+++ b/docs/user-manual/modules/ROOT/nav.adoc
@@ -18,7 +18,6 @@
** xref:error-handler.adoc[Error handler]
** xref:using-osgi-blueprint-with-camel.adoc[Using OSGi blueprint with Camel]
** xref:using-propertyplaceholder.adoc[How to use Camel property placeholders]
-** xref:templating.adoc[Templating]
** xref:testing.adoc[Testing]
** xref:rest-dsl.adoc[Working with REST and Rest DSL]
** xref:writing-components.adoc[Writing Components]
diff --git a/docs/user-manual/modules/ROOT/pages/stream-caching.adoc b/docs/user-manual/modules/ROOT/pages/stream-caching.adoc
index c798a4c..394dd26 100644
--- a/docs/user-manual/modules/ROOT/pages/stream-caching.adoc
+++ b/docs/user-manual/modules/ROOT/pages/stream-caching.adoc
@@ -3,201 +3,25 @@
While stream types (like `StreamSource`, `InputStream` and `Reader`) are commonly used in messaging for performance reasons, they also have an important drawback: they can only be read once. In order to be able to work with message content multiple times, the stream needs to be cached.
-Streams are caching in memory. In Camel 2.0, large stream messages (over 64 KB in Camel 2.11 or older, and 128 KB from Camel 2.12 onwards) will be cached in a temporary file instead -- Camel itself will handle deleting the temporary file once the cached stream is no longer necessary.
+Streams are cached in memory. However, for large stream messages (over 128 KB) will be cached in a temporary file instead -- Camel itself will handle deleting the temporary file once the cached stream is no longer necessary.
-* In Camel 2.0 stream cache is default *disabled* out of the box.
-* In Camel 1.x stream cache is default *enabled* out of the box.
-
-[NOTE]
+[IMPORTANT]
====
-*StreamCache Affects your payload object*
+*StreamCache - Affecting the message payload*
The `StreamCache` will affect your payload object as it will replace the `Stream` payload with a `org.apache.camel.StreamCache` object.
This `StreamCache` is capable of being re-readable and thus possible to better be routed within Camel using redelivery or xref:{eip-vc}:eips:content-based-router-eip.adoc[Content Based Router] or the likes.
-However to not change the payload under the covers without the end user really knowing we changed the default in Camel 2.0 to *disabled*. So in Camel 2.0 you have to explicit enable it if you want to use it.
+However, to not change the payload under the covers without the end user really knowing then stream caching is by default disabled.
====
-TIP: If using Camel 2.12 onwards then see xref:stream-caching.adoc[Using StreamCachingStrategy] further below which is the recommended way to configure stream caching options.
-
-[[Streamcaching-Enablingstreamcaching]]
-== Enabling stream caching
-
-In Apache Camel, you can explicitly enable stream caching for a single route with the `streamCaching` DSL method:
-
-[source,java]
-----
-from("jbi:service:http://foo.bar.org/MyService")
- .streamCaching()
- .to("jbi:service:http://foo.bar.org/MyOtherService");
-----
-
-In Spring XML you enable it by setting the `streamCache="true"` attribute on the route tag:
+In order to determine if a message payload requires caching, then Camel uses
+the xref:type-converter.adoc[Type Converter] functionality, to determine if
+the message payload type can be converted into an `org.apache.camel.StreamCache` instance.
-[source,xml]
-----
-<route streamCache="true">
- <from uri="jbi:service:http://foo.bar.org/MyService"/>
- <to uri="jbi:service:http://foo.bar.org/MyOtherService"/>
-</route>
-----
+== Configuring Stream Caching
-[[Streamcaching-Scopes]]
-=== Scopes
-
-`StreamCache` supports the global and per route scope. So by setting the `streamCache` attribute on `camelContext` you can enable/disable it globally:
-
-[source,xml]
-----
-<camelContext streamCache="true">
- ...
-</camelContext>
-----
-
-The route scope is configured by the `streamCache` attribute on the `<route>` tag such as:
-
-[source,xml]
-----
-<route streamCache="true">
- <from uri="jbi:service:http://foo.bar.org/MyService"/>
- <to uri="jbi:service:http://foo.bar.org/MyOtherService"/>
-</route>
-----
-
-You can mix and match for instance you can enable it globally and disable it on a particular route such as:
-
-[source,xml]
-----
-<camelContext streamCache="true">
- <route>
- <from uri="jbi:service:http://foo.bar.org/MyService"/>
- <to uri="jbi:service:http://foo.bar.org/MyOtherService"/>
- </route>
-
- <route streamCache="false">
- <from uri="jms:queue:foo"/>
- <to uri="jms:queue:bar"/>
- </route>
-</camelContext>
-----
-
-[[Streamcaching-EnablingfromJavaDSL]]
-=== Enabling from Java DSL
-
-You can enable stream cache by setting the property on `CamelContext`, for instance in a `RouteBuilder` class:
-
-[source,java]
-----
-context.setStreamCache(true);
-
-from("jbi:service:http://foo.bar.org/MyService")
- .to("jbi:service:http://foo.bar.org/MyOtherService");
-----
-
-[[Streamcaching-Disablestreamcachingexplicitly]]
-=== Disable stream caching explicitly
-
-If you have enabled stream caching globally on the `CamelContext` and you want to disable it for certain routes in a selective manner, you can use the following syntax.
-
-Spring DSL:
-
-[source,xml]
-----
-<camelContext streamCache="true">
- <route streamCache="false">
- <from uri="jetty:http://0.0.0.0:9090"/>
- <to uri="file:target/incoming"/>
- </route>
-</camelContext>
-----
-
-Java DSL:
-
-[source,java]
-----
-context.setStreamCache(true);
-
-from("jetty:http://0.0.0.0:9090").noStreamCaching()
- .to("file:target/incoming");
-----
-
-[[Streamcaching-Streamingcachetofiles]]
-== Streaming cache to files
-
-When stream cache is enabled it will by default spool big streams to files instead of keeping them in memory. The default threshold is 64 KB but you can configure it with the following properties:
-
-[width="100%",cols="20%,20%,60%",options="header"]
-|=======================================================================
-| Property | Default | Description
-
-| CamelCachedOutputStreamBufferSize | 2 KB
-| *Camel 2.9.4, 2.10.2, 2.11.0:* Size in bytes of the buffer used in the stream.
-
-| CamelCachedOutputStreamThreshold | 64 KB or 128 KB
-| 64 KB for *Camel 2.11* or older. 128 KB for *Camel 2.12* onwards. 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.
-
-| CamelCachedOutputStreamOutputDirectory | java.io.tmpdir
-| Base directory where temporary files for spooled streams should be stored.
-
-| CamelCachedOutputStreamCipherTransformation | null
-| *Camel 2.11.0:* 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).
-|=======================================================================
-
-You set these properties on the `CamelContext` as shown below, where we use a 1 MB threshold to spool to disk for messages bigger than 1 MB:
-
-[source,java]
-----
-context.getGlobalOptions().put(CachedOutputStream.TEMP_DIR, "/tmp/cachedir");
-context.getGlobalOptions().put(CachedOutputStream.THRESHOLD, "1048576");
-context.getGlobalOptions().put(CachedOutputStream.BUFFER_SIZE, "131072");
-// to enable encryption using RC4
-// context.getGlobalOptions().put(CachedOutputStream.CIPHER_TRANSFORMATION, "RC4");
-----
-
-And in XML you do:
-
-[source,xml]
-----
-<camelContext xmlns="http://camel.apache.org/schema/blueprint">
-
- <!-- disable stream caching spool to disk -->
- <properties>
- <property key="CamelCachedOutputStreamOutputDirectory" value="/tmp/cachedir"/>
- <property key="CamelCachedOutputStreamThreshold" value="1048576"/>
- <property key="CamelCachedOutputStreamBufferSize" value="131072"/>
- </properties>
-----
-
-[[Streamcaching-Disablingspoolingtodisk]]
-=== Disabling spooling to disk
-
-You can disable spooling to disk by setting a threshold of 0 or a negative value.
-
-[source,java]
-----
-// disable spooling to disk
-context.getGlobalOptions().put(CachedOutputStream.THRESHOLD, "-1");
-----
-
-And in XML you do:
-
-[source,xml]
-----
-<camelContext xmlns="http://camel.apache.org/schema/blueprint">
-
- <!-- disable stream caching spool to disk -->
- <properties>
- <property key="CamelCachedOutputStreamThreshold" value="-1"/>
- </properties>
-----
-
-[[Streamcaching-UsingStreamCachingStrategy]]
-== Using StreamCachingStrategy
-
-*Since Camel 2.12*
-
-Stream caching is from Camel 2.12 onwards intended to be configured using `org.apache.camel.spi.StreamCachingStrategy`.
-The old kind of configuration using properties on the xref:camelcontext.adoc[CamelContext] has been marked as deprecated.
+Stream caching is configured using `org.apache.camel.spi.StreamCachingStrategy`.
The strategy has the following options:
@@ -233,7 +57,6 @@ The strategy has the following options:
| Whether utilization statistics is enabled. By enabling this you can see these statics for example with JMX.
|=======================================================================
-[[Streamcaching-SpoolDirectorynamingpattern]]
=== SpoolDirectory naming pattern
The following patterns is supported:
@@ -264,10 +87,9 @@ To store in `KARAF_HOME/tmp/bundleId` directory:
context.getStreamCachingStrategy().setSpoolDirectory"${env:KARAF_HOME}/tmp/bundle#bundleId#");
----
-[[Streamcaching-UsingStreamCachingStrategyinJava]]
-=== Using StreamCachingStrategy in Java
+== Enabling StreamCachingStrategy in Java
-You can configure the StreamCachingStrategy in Java as shown below:
+You can configure the `StreamCachingStrategy` in Java as shown below:
[source,java]
----
@@ -278,21 +100,29 @@ context.getStreamCachingStrategy().setBufferSize(16 * 1024);
// context.getStreamCachingStrategy().setSpoolCipher("RC4");
----
-And remember to enable Stream caching on the CamelContext or on routes:
+And remember to enable Stream caching on the `CamelContext`:
[source,java]
----
context.setStreamCaching(true);
----
-[[Streamcaching-UsingStreamCachingStrategyinXML]]
-=== Using StreamCachingStrategy in XML
+or on routes:
-In XML you do:
+[source,java]
+----
+from("file:inbox")
+ .streamCaching()
+ .to("bean:foo");
+----
+
+== Enabling StreamCachingStrategy in XML
+
+In XML you can enable stream caching on the `<camelContext>` and then do the configuration in the `streamCaching` element:
[source,xml]
----
-<camelContext streamCache="true" xmlns="http://camel.apache.org/schema/blueprint">
+<camelContext streamCache="true">
<streamCaching id="myCacheConfig" bufferSize="16384" spoolDirectory="/tmp/cachedir" spoolThreshold="65536"/>
@@ -304,22 +134,6 @@ In XML you do:
</camelContext>
----
-You can also define a `<bean>` instead of using the `<streamCaching>` tag:
-
-[source,xml]
-----
-<!-- define a bean of type StreamCachingStrategy which CamelContext will automatic use -->
-<bean id="streamStrategy" class="org.apache.camel.impl.DefaultStreamCachingStrategy">
- <property name="spoolDirectory" value="/tmp/cachedir"/>
- <property name="spoolThreshold" value="65536"/>
- <property name="bufferSize" value="16384"/>
-</bean>
-
-<!-- remember to enable stream caching -->
-<camelContext streamCaching="true" xmlns="http://camel.apache.org/schema/spring">
-----
-
-[[Streamcaching-UsingspoolUsedHeapMemoryThreshold]]
=== Using spoolUsedHeapMemoryThreshold
By default stream caching will spool only big payloads (128 KB or bigger) to disk. However you can also set the `spoolUsedHeapMemoryThreshold` option which is a percentage of used heap memory. This can be used to also spool to disk when running low on memory.
@@ -349,15 +163,14 @@ If we only want to spool to disk if we run low on memory then we can set:
then we do not use the `spoolThreshold` rule, and only the heap memory based is in use.
-By default the upper limit of the used heap memory is based on the maximum heap size. Though you can also configure to use the committed heap size as the upper limit, this is done using the `spoolUsedHeapMemoryThreshold` option as shown below:
+By default, the upper limit of the used heap memory is based on the maximum heap size. Though you can also configure to use the committed heap size as the upper limit, this is done using the `spoolUsedHeapMemoryThreshold` option as shown below:
[source,xml]
----
<streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolUsedHeapMemoryThreshold="70" spoolUsedHeapMemoryLimit="Committed"/>
----
-[[Streamcaching-UsingcustomSpoolRuleimplementations]]
-=== Using custom SpoolRule implementations
+== Using custom SpoolRule implementations
You can implement your custom rules to determine if the stream should be spooled to disk. This can be done by implementing the interface `org.apache.camel.spi.StreamCachingStrategy.SpoolRule` which has a single method:
@@ -391,7 +204,3 @@ Using the spoolRules attribute on `<streamCaching>`. if you have more rules, the
<streamCaching id="myCacheConfig" spoolDirectory="/tmp/cachedir" spoolRules="mySpoolRule,myOtherSpoolRule"/>
----
-[[Streamcaching-Howitworks]]
-== How it works
-
-In order to determine if a type requires caching, we leverage the type converter feature. Any type that requires stream caching can be converted into an `org.apache.camel.StreamCache` instance.
diff --git a/docs/user-manual/modules/ROOT/pages/templating.adoc b/docs/user-manual/modules/ROOT/pages/templating.adoc
deleted file mode 100644
index 70c85cf..0000000
--- a/docs/user-manual/modules/ROOT/pages/templating.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-[[Templating-Templating]]
-= Templating
-
-When you are testing distributed systems its a very common requirement
-to have to stub out certain external systems with some stub so that you
-can test other parts of the system until a specific system is available
-or written etc.
-
-A great way to do this is using some kind of Template system to generate
-responses to requests generating a dynamic message using a mostly-static
-body.
-
-There are a number of templating components included in the Camel
-distribution you could use
-
-* xref:components::freemarker-component.adoc[FreeMarker]
-* xref:components::mustache-component.adoc[Mustache]
-* xref:components::string-template-component.adoc[StringTemplate]
-* xref:components::velocity-component.adoc[Velocity]
-* xref:components::xquery-component.adoc[XQuery]
-* xref:components::xslt-component.adoc[XSLT]
-
-or the following external Camel components
-
-* https://scalate.github.io/scalate/camel.html[Scalate]
-
-[[Templating-Example]]
-== Example
-
-Here's a simple example showing how we can respond to InOut requests on
-the *My.Queue* queue on xref:components::activemq-component.adoc[ActiveMQ] with a template
-generated response. The reply would be sent back to the JMSReplyTo
-Destination.
-
-[source,syntaxhighlighter-pre]
-----
-from("activemq:My.Queue").
- to("velocity:com/acme/MyResponse.vm");
-----
-
-If you want to use InOnly and consume the message and send it to another
-destination you could use
-
-[source,syntaxhighlighter-pre]
-----
-from("activemq:My.Queue").
- to("velocity:com/acme/MyResponse.vm").
- to("activemq:Another.Queue");
-----
-