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 072b29d068f76bf8ac4dd42c4f26fe02f0da10e2 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 0a6959376091..046c176a5a17 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 0a6959376091..046c176a5a17 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_:
