This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch camel-4.22.x
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/camel-4.22.x by this push:
new dff6907776fd chore: Clarify Simple OGNL method calls vs built-in
substring function in docs
dff6907776fd is described below
commit dff6907776fd72c00b853bfce0f1dc42ffb7d745
Author: Claus Ibsen <[email protected]>
AuthorDate: Wed Sep 2 11:10:59 2026 +0200
chore: Clarify Simple OGNL method calls vs built-in substring function in
docs
OGNL invokes the real Java method (e.g. String.substring), which has
different semantics than the same-named built-in Simple functions such
as substring(head,tail) that support negative indices. Add clarifying
notes to the simple-ognl and simple-functions doc pages to avoid the
name-collision trap.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Signed-off-by: Claus Ibsen <[email protected]>
---
.../org/apache/camel/catalog/docs/simple-functions.adoc | 9 +++++++++
.../org/apache/camel/catalog/docs/simple-ognl.adoc | 17 +++++++++++++++++
.../docs/modules/languages/pages/simple-functions.adoc | 9 +++++++++
.../main/docs/modules/languages/pages/simple-ognl.adoc | 17 +++++++++++++++++
4 files changed, 52 insertions(+)
diff --git
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/simple-functions.adoc
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/simple-functions.adoc
index f55ba4f45312..20f040941505 100644
---
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/simple-functions.adoc
+++
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/simple-functions.adoc
@@ -578,6 +578,15 @@ The `substring`, `substringBefore`, and `substringAfter`
functions are all simil
Suppose the message body contains `ABCDEFGHIJK` then `${substring(3)}` returns
`DEFGHIJK`, and `${substring(-3)}` returns `ABCDEFGH`.
If you want to clip the first and last character you can use
`${substring(1,-1)}` returning `BCDEFGHIJ`.
+[NOTE]
+====
+These `substring` functions are Camel functions with their own semantics (such
as negative numbers clipping
+from the end). They are *not* the same as calling Java's
`java.lang.String.substring` via
+xref:simple-ognl.adoc[OGNL]. For example `${substring(-3)}` (function) clips
the last three characters,
+whereas `${body.substring(-3)}` (OGNL) invokes `String.substring(-3)` directly
and throws
+`StringIndexOutOfBoundsException`.
+====
+
Now suppose the message body contains `Hello great big World how are you`.
Then `${substringBefore('World')}` return `"Hello great big "`.
diff --git
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/simple-ognl.adoc
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/simple-ognl.adoc
index 56a429400d4f..a79ab80ca0fa 100644
---
a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/simple-ognl.adoc
+++
b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/simple-ognl.adoc
@@ -29,6 +29,23 @@ Camel's OGNL support is for invoking methods only. You
cannot access fields. Cam
When using *OGNL* then `camel-bean` JAR is required to be on the classpath.
====
+[NOTE]
+====
+OGNL invokes the *real Java method* using standard Java semantics. For example
`${body.substring(2)}`
+calls `java.lang.String.substring(int)` directly.
+
+This is *not* the same as the built-in xref:simple-functions.adoc[Simple
function] of the same name.
+A function such as `${substring(2)}` (with no object prefix) is a Camel
function with its own semantics;
+for example it accepts negative numbers to clip from the end. By contrast
`${body.substring(-2)}` calls the
+JDK method, which throws `StringIndexOutOfBoundsException` because
`java.lang.String` does not accept a
+negative index.
+
+So when you want Camel's function semantics, use the built-in functions
(optionally passing the source as an
+argument, such as `${substring(0,-2,${header.foo})}`), and reserve OGNL
dot-notation for invoking genuine
+Java methods on the object. For fluent, function-based transformations you can
also chain built-in functions
+with the xref:simple-advanced.adoc[chain operator] `~>`.
+====
+
=== Built-in Functions supporting OGNL
The following functions support _OGNL syntax_:
diff --git
a/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-functions.adoc
b/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-functions.adoc
index f55ba4f45312..20f040941505 100644
---
a/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-functions.adoc
+++
b/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-functions.adoc
@@ -578,6 +578,15 @@ The `substring`, `substringBefore`, and `substringAfter`
functions are all simil
Suppose the message body contains `ABCDEFGHIJK` then `${substring(3)}` returns
`DEFGHIJK`, and `${substring(-3)}` returns `ABCDEFGH`.
If you want to clip the first and last character you can use
`${substring(1,-1)}` returning `BCDEFGHIJ`.
+[NOTE]
+====
+These `substring` functions are Camel functions with their own semantics (such
as negative numbers clipping
+from the end). They are *not* the same as calling Java's
`java.lang.String.substring` via
+xref:simple-ognl.adoc[OGNL]. For example `${substring(-3)}` (function) clips
the last three characters,
+whereas `${body.substring(-3)}` (OGNL) invokes `String.substring(-3)` directly
and throws
+`StringIndexOutOfBoundsException`.
+====
+
Now suppose the message body contains `Hello great big World how are you`.
Then `${substringBefore('World')}` return `"Hello great big "`.
diff --git
a/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-ognl.adoc
b/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-ognl.adoc
index 56a429400d4f..a79ab80ca0fa 100644
---
a/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-ognl.adoc
+++
b/core/camel-core-languages/src/main/docs/modules/languages/pages/simple-ognl.adoc
@@ -29,6 +29,23 @@ Camel's OGNL support is for invoking methods only. You
cannot access fields. Cam
When using *OGNL* then `camel-bean` JAR is required to be on the classpath.
====
+[NOTE]
+====
+OGNL invokes the *real Java method* using standard Java semantics. For example
`${body.substring(2)}`
+calls `java.lang.String.substring(int)` directly.
+
+This is *not* the same as the built-in xref:simple-functions.adoc[Simple
function] of the same name.
+A function such as `${substring(2)}` (with no object prefix) is a Camel
function with its own semantics;
+for example it accepts negative numbers to clip from the end. By contrast
`${body.substring(-2)}` calls the
+JDK method, which throws `StringIndexOutOfBoundsException` because
`java.lang.String` does not accept a
+negative index.
+
+So when you want Camel's function semantics, use the built-in functions
(optionally passing the source as an
+argument, such as `${substring(0,-2,${header.foo})}`), and reserve OGNL
dot-notation for invoking genuine
+Java methods on the object. For fluent, function-based transformations you can
also chain built-in functions
+with the xref:simple-advanced.adoc[chain operator] `~>`.
+====
+
=== Built-in Functions supporting OGNL
The following functions support _OGNL syntax_:
