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 ec88e61f721c [Documentation] Update xtokenize-language.adoc (#25977)
ec88e61f721c is described below
commit ec88e61f721cd83d4d166c5af39e0aa4924a5749
Author: Raymond Meester <[email protected]>
AuthorDate: Tue Sep 1 09:52:43 2026 +0200
[Documentation] Update xtokenize-language.adoc (#25977)
* Update xtokenize-language.adoc
- Clarify distinction between XML tokenize (xtokenize) and convential
tokenize.
- Add need Maven dependency
- Add example
* Apply suggestion from @davsclaus
Co-authored-by: Claus Ibsen <[email protected]>
* Update xtokenize-language.adoc
---------
Co-authored-by: Claus Ibsen <[email protected]>
---
.../camel/catalog/docs/xtokenize-language.adoc | 130 +++++++++++++++++++--
.../src/main/docs/xtokenize-language.adoc | 130 +++++++++++++++++++--
2 files changed, 246 insertions(+), 14 deletions(-)
diff --git
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/xtokenize-language.adoc
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/xtokenize-language.adoc
index ef1cc8255696..aee6949120c6 100644
---
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/xtokenize-language.adoc
+++
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/xtokenize-language.adoc
@@ -9,13 +9,32 @@
*Since Camel {since}*
-The XML Tokenize language is a built-in language in `camel-stax`, which
-is a truly XML-aware tokenizer that can be used with the
xref:eips:split-eip.adoc[Split] EIP
-as the conventional xref:tokenize-language.adoc[Tokenize] to efficiently and
-effectively tokenize XML documents.
+The XML Tokenize language (xtokenize) is a tokenizer specifically designed for
+XML documents. Unlike the conventional xref:tokenize-language.adoc[Tokenize
language], which is primarily a
+text-based tokenizer, XML Tokenize uses a StAX parser to interpret the XML
+structure while producing tokens.
-XML Tokenize is capable of not only recognizing XML namespaces and
hierarchical structures of the document
-but also more efficiently tokenizing XML documents than the conventional
xref:tokenize-language.adoc[Tokenize] language.
+The conventional Tokenize language also provides an xml option for XML-aware
+tokenization (xml=true). This should not be confused with XML Tokenize:
xtokenize
+uses different tokenization semantics and is intended for different use cases.
+
+Use xtokenize when XML structure or namespaces are important, or when you want
+a tokenizer specifically designed for XML documents. Use the conventional
+Tokenize language when you primarily need text-based
+tokenization and XML awareness is sufficient for your use case.
+
+Maven users will need to add the following dependency to their `pom.xml`
+for this language:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-stax</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel core version -->
+</dependency>
+----
== XML Tokenizer Options
@@ -86,4 +105,101 @@ If the expression declares namespaces inline as well, then
the inline namespaces
== Example
-See xref:eips:split-eip.adoc[Split EIP], which has examples using the XML
Tokenize language.
+Suppose the input XML contains multiple orders:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<orders xmlns="urn:shop">
+ <order>
+ <id>1001</id>
+ <customer>John</customer>
+ </order>
+ <order>
+ <id>1002</id>
+ <customer>Jane</customer>
+ </order>
+</orders>
+----
+
+The XML Tokenize language can be used with the Split EIP to split the document
+into one message for each `order` element.
+
+[tabs]
+====
+Java::
++
+[source,java]
+----
+var ns = new org.apache.camel.support.builder.Namespaces("shop", "urn:shop");
+
+from("direct:start")
+ .split()
+ .xtokenize("//shop:order", 'i', ns)
+ .streaming()
+ .to("mock:order");
+----
+
+XML::
++
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <split streaming="true">
+ <xtokenize>//shop:order
+ <namespace key="shop" value="urn:shop"/>
+ </xtokenize>
+ <to uri="mock:order"/>
+ </split>
+</route>
+----
+
+YAML::
++
+[source,yaml]
+----
+- route:
+ from:
+ uri: 'direct:start'
+ steps:
+ - split:
+ streaming: 'true'
+ expression:
+ xtokenize:
+ expression: '//shop:order'
+ namespace:
+ - key: shop
+ value: 'urn:shop'
+ steps:
+ - to:
+ uri: 'mock:order'
+----
+====
+
+The Split EIP produces two messages. The body of the first message is:
+
+.Output message 1
+[source,xml]
+----
+<order xmlns="urn:shop">
+ <id>1001</id>
+ <customer>John</customer>
+</order>
+----
+
+The body of the second message is:
+
+.Output message 2
+[source,xml]
+----
+<order xmlns="urn:shop">
+ <id>1002</id>
+ <customer>Jane</customer>
+</order>
+----
+
+The `shop` namespace is mapped to `urn:shop`, allowing the XPath expression
+`//shop:order` to identify the namespaced `order` elements.
+
+See the xref:eips:split-eip.adoc[Split EIP] for more examples.
diff --git a/components/camel-stax/src/main/docs/xtokenize-language.adoc
b/components/camel-stax/src/main/docs/xtokenize-language.adoc
index ef1cc8255696..aee6949120c6 100644
--- a/components/camel-stax/src/main/docs/xtokenize-language.adoc
+++ b/components/camel-stax/src/main/docs/xtokenize-language.adoc
@@ -9,13 +9,32 @@
*Since Camel {since}*
-The XML Tokenize language is a built-in language in `camel-stax`, which
-is a truly XML-aware tokenizer that can be used with the
xref:eips:split-eip.adoc[Split] EIP
-as the conventional xref:tokenize-language.adoc[Tokenize] to efficiently and
-effectively tokenize XML documents.
+The XML Tokenize language (xtokenize) is a tokenizer specifically designed for
+XML documents. Unlike the conventional xref:tokenize-language.adoc[Tokenize
language], which is primarily a
+text-based tokenizer, XML Tokenize uses a StAX parser to interpret the XML
+structure while producing tokens.
-XML Tokenize is capable of not only recognizing XML namespaces and
hierarchical structures of the document
-but also more efficiently tokenizing XML documents than the conventional
xref:tokenize-language.adoc[Tokenize] language.
+The conventional Tokenize language also provides an xml option for XML-aware
+tokenization (xml=true). This should not be confused with XML Tokenize:
xtokenize
+uses different tokenization semantics and is intended for different use cases.
+
+Use xtokenize when XML structure or namespaces are important, or when you want
+a tokenizer specifically designed for XML documents. Use the conventional
+Tokenize language when you primarily need text-based
+tokenization and XML awareness is sufficient for your use case.
+
+Maven users will need to add the following dependency to their `pom.xml`
+for this language:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-stax</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel core version -->
+</dependency>
+----
== XML Tokenizer Options
@@ -86,4 +105,101 @@ If the expression declares namespaces inline as well, then
the inline namespaces
== Example
-See xref:eips:split-eip.adoc[Split EIP], which has examples using the XML
Tokenize language.
+Suppose the input XML contains multiple orders:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<orders xmlns="urn:shop">
+ <order>
+ <id>1001</id>
+ <customer>John</customer>
+ </order>
+ <order>
+ <id>1002</id>
+ <customer>Jane</customer>
+ </order>
+</orders>
+----
+
+The XML Tokenize language can be used with the Split EIP to split the document
+into one message for each `order` element.
+
+[tabs]
+====
+Java::
++
+[source,java]
+----
+var ns = new org.apache.camel.support.builder.Namespaces("shop", "urn:shop");
+
+from("direct:start")
+ .split()
+ .xtokenize("//shop:order", 'i', ns)
+ .streaming()
+ .to("mock:order");
+----
+
+XML::
++
+[source,xml]
+----
+<route>
+ <from uri="direct:start"/>
+ <split streaming="true">
+ <xtokenize>//shop:order
+ <namespace key="shop" value="urn:shop"/>
+ </xtokenize>
+ <to uri="mock:order"/>
+ </split>
+</route>
+----
+
+YAML::
++
+[source,yaml]
+----
+- route:
+ from:
+ uri: 'direct:start'
+ steps:
+ - split:
+ streaming: 'true'
+ expression:
+ xtokenize:
+ expression: '//shop:order'
+ namespace:
+ - key: shop
+ value: 'urn:shop'
+ steps:
+ - to:
+ uri: 'mock:order'
+----
+====
+
+The Split EIP produces two messages. The body of the first message is:
+
+.Output message 1
+[source,xml]
+----
+<order xmlns="urn:shop">
+ <id>1001</id>
+ <customer>John</customer>
+</order>
+----
+
+The body of the second message is:
+
+.Output message 2
+[source,xml]
+----
+<order xmlns="urn:shop">
+ <id>1002</id>
+ <customer>Jane</customer>
+</order>
+----
+
+The `shop` namespace is mapped to `urn:shop`, allowing the XPath expression
+`//shop:order` to identify the namespaced `order` elements.
+
+See the xref:eips:split-eip.adoc[Split EIP] for more examples.
