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
The following commit(s) were added to refs/heads/main by this push:
new 3695a8126ecd CAMEL-16861: Update docs
3695a8126ecd is described below
commit 3695a8126ecd0fb938e4826b827e0120b6d5bfc1
Author: Claus Ibsen <[email protected]>
AuthorDate: Wed Feb 25 12:27:18 2026 +0100
CAMEL-16861: Update docs
---
docs/user-manual/modules/ROOT/pages/tracer.adoc | 80 ++++++++----
.../modules/ROOT/pages/transformer.adoc | 49 ++++---
.../modules/ROOT/pages/try-catch-finally.adoc | 142 +++++++++++++++++++--
.../modules/ROOT/pages/type-converter.adoc | 28 +++-
docs/user-manual/modules/ROOT/pages/validator.adoc | 2 +
5 files changed, 237 insertions(+), 64 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/tracer.adoc
b/docs/user-manual/modules/ROOT/pages/tracer.adoc
index 6cfebe077c95..19f5ad0f62af 100644
--- a/docs/user-manual/modules/ROOT/pages/tracer.adoc
+++ b/docs/user-manual/modules/ROOT/pages/tracer.adoc
@@ -3,19 +3,26 @@
Camel's tracer is used for logging message details during routing, where
you can see the route path of each message as they happen. Details of the
message is also logged such as the message body, and headers.
-TIP: There is an alternative tracer that captures the messages in a
xref:backlog-tracer.adoc[Backlog Tracer].
+TIP: There is an alternative tracer that captures the messages in a
xref:backlog-tracer.adoc[Backlog Tracer] for on-demand tracing. For example
tools, Camel JBang, Hawtio and others are using this.
== Enabling Tracing
-In Java you set tracing on `CamelContext`:
+The logging tracing is easily enabled by setting a single flag.
+[tabs]
+====
+
+Java::
++
+You enable tracing on the `CamelContext`:
++
[source,java]
----
context.setTracing(true);
----
-And in XML DSL:
-
+Spring XML::
++
[source,xml]
----
<camelContext trace="true"
xmlns="http://activemq.apache.org/camel/schema/spring";>
@@ -23,27 +30,35 @@ And in XML DSL:
</camelContext>
----
-And in Spring Boot
-
-[source,text]
+Application Properties::
++
+For example when using Spring Boot or Quarkus
++
+[source,properties]
----
camel.main.tracing = true
----
+====
=== Setting Tracing in Standby mode
-By default Camel optimizes and opt-out tracing. Therefore, you would either
have to enable tracing from the startup,
+By default, Camel optimizes and opt-out tracing. Therefore, you would either
have to enable tracing from the startup,
or turn on standby mode, to allow tracing to be enabled later during runtime.
To set tracing in standby mode you can do:
+[tabs]
+====
+
+Java::
++
[source,java]
----
context.setTracingStandby(true);
----
-And in XML DSL:
-
+Spring XML::
++
[source,xml]
----
<camelContext trace="standby"
xmlns="http://activemq.apache.org/camel/schema/spring";>
@@ -51,15 +66,20 @@ And in XML DSL:
</camelContext>
----
-And in Spring Boot
-
-[source,text]
+Application Properties::
++
+For example when using Spring Boot or Quarkus
++
+[source,properties]
----
camel.main.tracing-standby = true
----
+====
+
+If tracer is in standby mode, then tracing is made available, and can be
enabled later during runtime.
+This requires to either use JMX or Java to turn on the tracing:
-If tracer is in standby mode, then tracing is made available, and can be
enabled during runtime.
-This requires to either use JMX or enable via Java code:
+For example in Java:
[source,java]
----
@@ -83,17 +103,25 @@ The tracer outputs the logging with a prefix with the
following information:
This output is assembled using the following default format:
-- %-4.4s [%-12.12s] [%-33.33s]
+[source,text]
+----
+%-4.4s [%-12.12s] [%-33.33s]
+----
-The default format can be customized using, for exameple to use wider columns:
+The default format can be customized using, for example to use wider columns:
+[tabs]
+====
+
+Java::
++
[source,java]
----
context.setTracingLoggingFormat("%-4.4s [%-30.30s] [%-50.50s]");
----
-And in XML DSL:
-
+Spring XML::
++
[source,xml]
----
<camelContext trace="true" traceLoggingFormat="%-4.4s [%-30.30s] [%-50.50s]">
@@ -101,16 +129,16 @@ And in XML DSL:
</camelContext>
----
-And in Spring Boot
-
+Application Properties::
++
[source,properties]
----
camel.main.tracing-logging-format = %-4.4s [%-30.30s] [%-50.50s]
----
+====
-And in Camel Main / Quarkus
+== See Also
-[source,properties]
-----
-camel.main.tracing-logging-format = %-4.4s [%-30.30s] [%-50.50s]
-----
+- xref:backlog-tracer.adoc[Backlog Tracer]
+- xref:debugger.adoc[]
+- xref:backlog-debugger.adoc[Backlog Debugger]
\ No newline at end of file
diff --git a/docs/user-manual/modules/ROOT/pages/transformer.adoc
b/docs/user-manual/modules/ROOT/pages/transformer.adoc
index 3f97ed2c066d..93866cf0359a 100644
--- a/docs/user-manual/modules/ROOT/pages/transformer.adoc
+++ b/docs/user-manual/modules/ROOT/pages/transformer.adoc
@@ -11,6 +11,8 @@ looks for a `Transformer` which transforms from the current
message type to the
type and apply. Once transform succeed or message is already in expected type,
then the message
data type is updated.
+NOTE: Currently, transformers is only supported in Java DSL and the classic
Spring XML.
+
== Data type format
[source,text]
@@ -28,8 +30,8 @@ If you only specify *scheme* then it hits all the data types
which has that sche
[width="100%",cols="25%,75%",options="header",]
|===
| Transformer | Description
-| Data Format Transformer | Transform with using Data Format
-| Endpoint Transformer | Transform with using Endpoint
+| Data Format Transformer | Transform with using xref:data-format.adoc[]
+| Endpoint Transformer | Transform with using xref:endpoint.adoc[]
| Custom Transformer | Transform with using custom transformer class.
Transformer must be a subclass of `org.apache.camel.spi.Transformer`
| Loading Transformer | Loads multiple transformer implementations (e.g. via
annotation classpath scan). Also preloads known default Camel transformer
implementations.
|===
@@ -51,6 +53,8 @@ Transformer implementations may use `scheme:name` or the
combination of `fromTyp
When using the `scheme:name` identifier users may reference the transformer by
its full name in a route.
+Here we declare the route has a given expected input type:
+
[tabs]
====
Java::
@@ -66,13 +70,11 @@ XML::
+
[source,xml]
----
-<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";>
- <route>
- <from uri="direct:abc"/>
- <inputType urn="myScheme:myTransformer"/>
- <to uri="..."/>
- </route>
-</camelContext>
+<route>
+ <from uri="direct:abc"/>
+ <inputType urn="myScheme:myTransformer"/>
+ <to uri="..."/>
+</route>
----
====
@@ -109,13 +111,14 @@ Java::
BindyDataFormat bindy = new BindyDataFormat();
bindy.setType(BindyType.Csv);
bindy.setClassType(com.example.Order.class);
+
transformer()
.fromType(com.example.Order.class)
.toType("csv:CSVOrder")
.withDataFormat(bindy);
----
-XML::
+Spring XML::
+
[source,xml]
----
@@ -136,6 +139,11 @@ XML::
Here is an example to specify endpoint URI in Java DSL:
+[tabs]
+====
+
+Java::
++
[source,java]
----
transformer()
@@ -144,12 +152,13 @@ transformer()
.withUri("component:componentPathOptions?mappingFile=myMapping.xml...");
----
-And here is an example to specify endpoint ref in XML DSL:
-
+Spring XML::
++
[source,xml]
----
<endpointTransformer ref="myEndpoint" fromType="xml" toType="json"/>
----
+====
== Custom Transformer Options
@@ -176,7 +185,7 @@ transformer()
.withJava(com.example.MyCustomTransformer.class);
----
-XML::
+Spring XML::
+
[source,xml]
----
@@ -204,10 +213,10 @@ Java::
[source,java]
----
transformer()
- .withDefaults()
+ .withDefaults();
----
-XML::
+Spring XML::
+
[source,xml]
----
@@ -224,10 +233,10 @@ Java::
[source,java]
----
transformer()
- .scan("org.apache.camel.transformer.standard")
+ .scan("org.apache.camel.transformer.standard");
----
-XML::
+Spring XML::
+
[source,xml]
----
@@ -267,7 +276,7 @@ transformer()
.withUri("xslt:transform.xsl");
----
-XML::
+Spring XML::
+
[source,xml]
----
@@ -280,7 +289,7 @@ XML::
----
====
-If you have following route definition, above transformer will be applied when
`direct:abc` endpoint sends the message to `direct:xyz`:
+If you have the following route definition, above transformer will be applied
when `direct:abc` endpoint sends the message to `direct:xyz`:
[tabs]
====
@@ -297,7 +306,7 @@ from("direct:xyz")
.to("somewhere:else");
----
-XML::
+Spring XML::
+
[source,xml]
----
diff --git a/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc
b/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc
index e141427ad98c..30a33b692661 100644
--- a/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc
+++ b/docs/user-manual/modules/ROOT/pages/try-catch-finally.adoc
@@ -11,16 +11,25 @@ So we have:
- `doFinally`
- `end` to end the block in Java DSL
+[IMPORTANT]
+====
When using `doTry ... doCatch ... doFinally` then the regular Camel
xref:error-handler.adoc[Error Handler] is not in use; meaning any
`onException` or the likes does not trigger.
+
The reason is that
`doTry ... doCatch ... doFinally` is in fact its own error handler and mimics
how try/catch/finally works in Java.
+====
== Using doTry ... doCatch ... doFinally
In the route below we have all of them in action:
+[tabs]
+====
+
+Java::
++
[source,java]
----
from("direct:start")
@@ -34,8 +43,9 @@ from("direct:start")
.end();
----
-And in XML DSL
+XML::
++
[source,xml]
----
<route>
@@ -55,11 +65,43 @@ And in XML DSL
</route>
----
+YAML::
++
+[source,yaml]
+----
+- route:
+ from:
+ uri: direct:start
+ steps:
+ - doTry:
+ steps:
+ - process:
+ ref: processorFail
+ - to:
+ uri: mock:result
+ - doCatch:
+ exception:
+ - java.io.IOException
+ - java.lang.IllegalStateException
+ steps:
+ - to:
+ uri: mock:catch
+ - doFinally:
+ steps:
+ - to:
+ uri: mock:finally
+----
+====
+
=== Using onWhen with doCatch
You can use xref:predicate.adoc[Predicate]s with `doCatch` to make it runtime
determine if the block should be triggered or not.
In our case, we only want to trigger if the caused exception message contains
the *damn* word.
+[tabs]
+====
++
+Java::
[source,java]
----
from("direct:start")
@@ -75,8 +117,8 @@ from("direct:start")
.end();
----
-And in XML DSL
-
+XML::
++
[source,xml]
----
<route>
@@ -103,6 +145,44 @@ And in XML DSL
</route>
----
+YAML::
++
+[source,yaml]
+----
+- route:
+ from:
+ uri: direct:start
+ steps:
+ - doTry:
+ steps:
+ - process:
+ ref: processorFail
+ - to:
+ uri: mock:result
+ - doCatch:
+ exception:
+ - java.io.IOException
+ - java.lang.IllegalStateException
+ steps:
+ - onWhen:
+ expression:
+ simple:
+ expression: "${exception.message} contains 'Damn'"
+ - to:
+ uri: mock:catch
+ - doCatch:
+ exception:
+ - org.apache.camel.CamelExchangeException
+ steps:
+ - to:
+ uri: mock:catchCamel
+ - doFinally:
+ steps:
+ - to:
+ uri: mock:finally
+----
+====
+
=== Use end() to end the block
Notice when using Java DSL we must use `end()` to indicate where the try ...
catch ... finally block ends.
@@ -145,7 +225,7 @@ So what you must do is to end the doCatch block correct
(notice how we use `endD
[source,java]
----
-from("direct:test").routeId("myroute")
+from("direct:test")
.doTry().
doTry().
throwException(new IllegalArgumentException("Forced by me"))
@@ -159,23 +239,63 @@ from("direct:test").routeId("myroute")
.end();
----
-And by using the `endDoTry()` we can end the block correctly, and an XML
representation of the route would be as follows:
+And by using the `endDoTry()` we can end the block correctly, and an XML or
YAML representation of the route would be as follows:
+
+[tabs]
+====
+XML::
++
[source,xml]
----
<route>
<from uri="direct:test"/>
<doTry>
<doTry>
- <throwException id="throwException1"/>
- <doCatch id="doCatch1">
- <log id="log1" message="docatch 1"/>
- <throwException id="throwException2"/>
+ <throwException exceptionType="java.lang.IllegalArgumentException"
message="Forced by me"/>
+ <doCatch>
+ <exception>java.lang.Exception</exception>
+ <log message="docatch 1"/>
+ <throwException
exceptionType="java.lang.IllegalArgumentException" message="Second forced by
me"/>
</doCatch>
</doTry>
- <doCatch id="doCatch2">
- <log id="log2" message="docatch 2"/>
+ <doCatch>
+ <exception>java.lang.Exception</exception>
+ <log message="docatch 2"/>
</doCatch>
</doTry>
</route>
----
+
+YAML::
++
+[source,yaml]
+----
+- route:
+ from:
+ uri: direct:test
+ steps:
+ - doTry:
+ steps:
+ - doTry:
+ steps:
+ - throwException:
+ message: Forced by me
+ exceptionType: java.lang.IllegalArgumentException
+ - doCatch:
+ exception:
+ - java.lang.Exception
+ steps:
+ - log:
+ message: docatch 1
+ - throwException:
+ message: Second forced by me
+ exceptionType: java.lang.IllegalArgumentException
+ - doCatch:
+ exception:
+ - java.lang.Exception
+ steps:
+ - log:
+ message: docatch 2
+----
+====
diff --git a/docs/user-manual/modules/ROOT/pages/type-converter.adoc
b/docs/user-manual/modules/ROOT/pages/type-converter.adoc
index 7b5940baaba6..38201449f5c8 100644
--- a/docs/user-manual/modules/ROOT/pages/type-converter.adoc
+++ b/docs/user-manual/modules/ROOT/pages/type-converter.adoc
@@ -33,7 +33,7 @@ interface. The interface has several methods, however the
most important and com
<T> T convertTo(Class<T> type, Exchange exchange, Object value) throws
TypeConversionException;
----
-This API is used by Camel when it converts an object from one type to another.
However if
+This API is used by Camel when it converts an object from one type to another.
However, if
you pay attention then this API only has the result type in the contract. The
input type
is inferred from the _value_ parameter.
@@ -72,8 +72,7 @@ and invoke these type converters at runtime via quick Java
method invocations (n
=== Type converter registry utilization statistics
NOTE: as of Camel 4.7.0, the statistics collector in the registry has been
made immutable.
-As such, enabling collection of statistics has to be done prior to creating
the type converter
-registry.
+As such, enabling collection of statistics has to be done prior to creating
the type converter registry.
Camel can gather utilization statistics of the runtime usage of type
converters. These statistics are available in xref:jmx.adoc[JMX] as well as
@@ -84,14 +83,19 @@ default as there is some performance overhead under very
high concurrent load.
Enabling statistics in Java:
+[tabs]
+====
+
+Java::
++
[source,java]
----
CamelContext context = ...;
context.setTypeConverterStatisticsEnabled(true);
----
-Enabling statistics in XML DSL:
-
+Spring XML::
++
[source,xml]
----
<camelContext typeConverterStatisticsEnabled="true">
@@ -99,6 +103,16 @@ Enabling statistics in XML DSL:
</camelContext>
----
+Application Properties::
++
+For example when using Spring Boot, Quarkus or Camel standalone, you can
configure this in `application.properties`:
++
+[source,properties]
+----
+camel.main.typeConverterStatisticsEnabled = true
+----
+====
+
== TypeConverter using @Converter annotation
All the type converters that come out of the box are coded as Java methods on
_converter_ classes.
@@ -173,8 +187,8 @@ public class IOConverter {
There are few limitations:
-- fallback converters are not supported
-- the order of the `@Converter` methods matters. If you have multiple
`@Converter` methods that accept as _from_ type
+- Fallback converters are not supported
+- The order of the `@Converter` methods matters. If you have multiple
`@Converter` methods that accept as _from_ type
types which are from the same class hierarchy then put the methods first that
are the most concrete.
For example in `camel-xml-jaxp` we have in the `XmlConverter` multiple
`@Converter` methods which can convert to `DomSource`.
diff --git a/docs/user-manual/modules/ROOT/pages/validator.adoc
b/docs/user-manual/modules/ROOT/pages/validator.adoc
index f7fa90801a63..e4376bee5325 100644
--- a/docs/user-manual/modules/ROOT/pages/validator.adoc
+++ b/docs/user-manual/modules/ROOT/pages/validator.adoc
@@ -4,6 +4,8 @@ Validator performs declarative validation of the message
according to the declar
_Input Type_ and/or _Output Type_ on a route definition which declares the
expected
message type.
+NOTE: Currently, validators is only supported in Java DSL and the classic
Spring XML.
+
== Data type format
