This is an automated email from the ASF dual-hosted git repository. davsclaus pushed a commit to branch fix/CAMEL-23816 in repository https://gitbox.apache.org/repos/asf/camel.git
commit 9f97bbc2e293d533493aac3c3141a53e50f5bdaf Author: Claus Ibsen <[email protected]> AuthorDate: Tue Jun 23 14:45:22 2026 +0200 CAMEL-23816: Improve descriptions in error handling model classes for catalog and MCP tools Co-Authored-By: Claude Opus 4.6 <[email protected]> --- .../org/apache/camel/model/CatchDefinition.java | 3 +- .../org/apache/camel/model/FinallyDefinition.java | 2 +- .../apache/camel/model/OnExceptionDefinition.java | 62 ++++++++++++++++------ .../camel/model/ThrowExceptionDefinition.java | 5 +- .../java/org/apache/camel/model/TryDefinition.java | 2 +- .../errorhandler/DeadLetterChannelDefinition.java | 6 ++- .../DefaultErrorHandlerDefinition.java | 43 +++++++++++---- 7 files changed, 91 insertions(+), 32 deletions(-) diff --git a/core/camel-core-model/src/main/java/org/apache/camel/model/CatchDefinition.java b/core/camel-core-model/src/main/java/org/apache/camel/model/CatchDefinition.java index 490cb81a39e2..3d92815f33ed 100644 --- a/core/camel-core-model/src/main/java/org/apache/camel/model/CatchDefinition.java +++ b/core/camel-core-model/src/main/java/org/apache/camel/model/CatchDefinition.java @@ -47,7 +47,8 @@ public class CatchDefinition extends OutputDefinition<CatchDefinition> { @XmlElement(name = "exception") @DslArg(renderType = "classList") private List<String> exceptions = new ArrayList<>(); - @Metadata(description = "Used for triggering doCatch in specific situations") + @Metadata(description = "An additional predicate that must evaluate to true for this doCatch to trigger." + + " Allows fine-grained control over which exceptions are caught based on the exchange state.") @XmlElement @AsPredicate private OnWhenDefinition onWhen; diff --git a/core/camel-core-model/src/main/java/org/apache/camel/model/FinallyDefinition.java b/core/camel-core-model/src/main/java/org/apache/camel/model/FinallyDefinition.java index 1dce56ebbc61..c0dfc3f99df9 100644 --- a/core/camel-core-model/src/main/java/org/apache/camel/model/FinallyDefinition.java +++ b/core/camel-core-model/src/main/java/org/apache/camel/model/FinallyDefinition.java @@ -27,7 +27,7 @@ import org.apache.camel.Exchange; import org.apache.camel.spi.Metadata; /** - * Path traversed when a try, catch, finally block exits + * Steps to execute after a doTry block completes, regardless of whether an exception was thrown or caught */ @Metadata(label = "error") @XmlRootElement(name = "doFinally") diff --git a/core/camel-core-model/src/main/java/org/apache/camel/model/OnExceptionDefinition.java b/core/camel-core-model/src/main/java/org/apache/camel/model/OnExceptionDefinition.java index 6f370f287beb..824b30a552dc 100644 --- a/core/camel-core-model/src/main/java/org/apache/camel/model/OnExceptionDefinition.java +++ b/core/camel-core-model/src/main/java/org/apache/camel/model/OnExceptionDefinition.java @@ -67,31 +67,53 @@ public class OnExceptionDefinition extends OutputDefinition<OnExceptionDefinitio private OnWhenDefinition onWhen; @XmlElement(name = "retryWhile") @AsPredicate - @Metadata(label = "advanced") + @Metadata(label = "advanced", + description = "Sets a predicate to control whether redelivery should continue." + + " Redelivery continues as long as the predicate evaluates to true.") private ExpressionSubElementDefinition retryWhile; @XmlElement(name = "redeliveryPolicy") private RedeliveryPolicyDefinition redeliveryPolicyType; @XmlAttribute(name = "redeliveryPolicyRef") - @Metadata(label = "advanced") + @Metadata(label = "advanced", + description = "Sets a reference to a redelivery policy to lookup in the registry to be used.") private String redeliveryPolicyRef; @XmlElement(name = "handled") @AsPredicate + @Metadata(description = "When handled is set to true, the exception is suppressed and not sent back to the caller." + + " The original route stops at the point of failure and only the steps in this onException block execute." + + " The response returned to the caller is whatever this onException block produces." + + " Use continued instead if you want to resume the original route from the point of failure.") private ExpressionSubElementDefinition handled; @XmlElement(name = "continued") @AsPredicate - @Metadata(label = "advanced") + @Metadata(label = "advanced", + description = "When continued is set to true, the exception is handled and routing continues from the point of failure." + + " Unlike handled, which stops the original route and only runs the onException block," + + " continued resumes the original route after the onException steps complete." + + " The exception is considered handled as well.") private ExpressionSubElementDefinition continued; @XmlAttribute(name = "onRedeliveryRef") - @Metadata(label = "advanced") + @Metadata(label = "advanced", + description = "Sets a reference to a processor that is invoked before each redelivery attempt." + + " Can be used to change the exchange before it is redelivered.") private String onRedeliveryRef; @XmlAttribute(name = "onExceptionOccurredRef") - @Metadata(label = "advanced") + @Metadata(label = "advanced", + description = "Sets a reference to a processor that is invoked just after an exception occurred." + + " Can be used to perform custom logging. Any exception thrown from this processor is ignored.") private String onExceptionOccurredRef; @XmlAttribute(name = "useOriginalMessage") - @Metadata(label = "advanced", javaType = "java.lang.Boolean") + @Metadata(label = "advanced", javaType = "java.lang.Boolean", + description = "If enabled, uses the original input message (body and headers) when the exchange" + + " is moved to the dead letter queue after all redelivery attempts have been exhausted." + + " Cannot be used together with useOriginalBody.") private String useOriginalMessage; @XmlAttribute(name = "useOriginalBody") - @Metadata(label = "advanced", javaType = "java.lang.Boolean") + @Metadata(label = "advanced", javaType = "java.lang.Boolean", + description = "If enabled, uses the original input message body (but not headers) when the exchange" + + " is moved to the dead letter queue after all redelivery attempts have been exhausted." + + " This allows enriching the message with custom headers while keeping the original body." + + " Cannot be used together with useOriginalMessage.") private String useOriginalBody; public OnExceptionDefinition() { @@ -217,7 +239,9 @@ public class OnExceptionDefinition extends OutputDefinition<OnExceptionDefinitio } /** - * Sets whether the exchange should be marked as handled or not. + * Sets whether the exception is handled. When true, the exception is suppressed and not sent back to the caller. + * The original route stops at the point of failure and only the steps in this onException block execute. + * The response returned to the caller is whatever this onException block produces. * * @param handled handled or not * @return the builder @@ -228,7 +252,9 @@ public class OnExceptionDefinition extends OutputDefinition<OnExceptionDefinitio } /** - * Sets whether the exchange should be marked as handled or not. + * Sets whether the exception is handled using a predicate. When the predicate evaluates to true, the exception is + * suppressed and not sent back to the caller. The original route stops at the point of failure and only the steps + * in this onException block execute. The response returned to the caller is whatever this onException block produces. * * @param handled predicate that determines true or false * @return the builder @@ -239,7 +265,9 @@ public class OnExceptionDefinition extends OutputDefinition<OnExceptionDefinitio } /** - * Sets whether the exchange should be marked as handled or not. + * Sets whether the exception is handled using an expression. When the expression evaluates to true, the exception is + * suppressed and not sent back to the caller. The original route stops at the point of failure and only the steps + * in this onException block execute. The response returned to the caller is whatever this onException block produces. * * @param handled expression that determines true or false * @return the builder @@ -263,9 +291,10 @@ public class OnExceptionDefinition extends OutputDefinition<OnExceptionDefinitio } /** - * Sets whether the exchange should be marked as handled or not. - * <p/> - * If this option is enabled then its considered handled as well. + * Sets whether the exchange should continue routing from the point of failure using a predicate. + * When the predicate evaluates to true, the exception is handled and routing resumes from the point of failure. + * Unlike handled, which stops the original route, continued lets the remaining route steps execute. + * The exception is considered handled as well. * * @param continued predicate that determines true or false * @return the builder @@ -276,9 +305,10 @@ public class OnExceptionDefinition extends OutputDefinition<OnExceptionDefinitio } /** - * Sets whether the exchange should be marked as handled or not. - * <p/> - * If this option is enabled then its considered handled as well. + * Sets whether the exchange should continue routing from the point of failure using an expression. + * When the expression evaluates to true, the exception is handled and routing resumes from the point of failure. + * Unlike handled, which stops the original route, continued lets the remaining route steps execute. + * The exception is considered handled as well. * * @param continued expression that determines true or false * @return the builder diff --git a/core/camel-core-model/src/main/java/org/apache/camel/model/ThrowExceptionDefinition.java b/core/camel-core-model/src/main/java/org/apache/camel/model/ThrowExceptionDefinition.java index d428bd4557f3..dab2fca6545f 100644 --- a/core/camel-core-model/src/main/java/org/apache/camel/model/ThrowExceptionDefinition.java +++ b/core/camel-core-model/src/main/java/org/apache/camel/model/ThrowExceptionDefinition.java @@ -40,12 +40,15 @@ public class ThrowExceptionDefinition extends NoOutputDefinition<ThrowExceptionD @XmlAttribute @DslArg(position = 1) + @Metadata(description = "The message text for the exception to be thrown. Supports simple language expressions.") private String message; @XmlAttribute @DslArg(position = 0, renderType = "class") + @Metadata(description = "The fully qualified class name of the exception to throw. Used together with message.") private String exceptionType; @XmlAttribute - @Metadata(label = "advanced") + @Metadata(label = "advanced", + description = "Reference to an existing exception instance to lookup from the registry and throw.") private String ref; public ThrowExceptionDefinition() { diff --git a/core/camel-core-model/src/main/java/org/apache/camel/model/TryDefinition.java b/core/camel-core-model/src/main/java/org/apache/camel/model/TryDefinition.java index d2233f84f806..3a89df120919 100644 --- a/core/camel-core-model/src/main/java/org/apache/camel/model/TryDefinition.java +++ b/core/camel-core-model/src/main/java/org/apache/camel/model/TryDefinition.java @@ -33,7 +33,7 @@ import org.apache.camel.spi.Metadata; import org.apache.camel.spi.annotations.DslProperty; /** - * Marks the beginning of a try, catch, finally block + * Wraps route steps in a try-catch-finally block for fine-grained exception handling within the route */ @Metadata(label = "eip,routing,error") @XmlRootElement(name = "doTry") diff --git a/core/camel-core-model/src/main/java/org/apache/camel/model/errorhandler/DeadLetterChannelDefinition.java b/core/camel-core-model/src/main/java/org/apache/camel/model/errorhandler/DeadLetterChannelDefinition.java index 26ef95f63da3..f353fa356ad3 100644 --- a/core/camel-core-model/src/main/java/org/apache/camel/model/errorhandler/DeadLetterChannelDefinition.java +++ b/core/camel-core-model/src/main/java/org/apache/camel/model/errorhandler/DeadLetterChannelDefinition.java @@ -35,9 +35,13 @@ import org.apache.camel.spi.Metadata; public class DeadLetterChannelDefinition extends DefaultErrorHandlerDefinition { @XmlAttribute(required = true) + @Metadata(description = "The endpoint URI where failed exchanges are sent after all redelivery attempts have been exhausted (the dead letter queue).") private String deadLetterUri; @XmlAttribute - @Metadata(label = "advanced", defaultValue = "true", javaType = "java.lang.Boolean") + @Metadata(label = "advanced", defaultValue = "true", javaType = "java.lang.Boolean", + description = "Whether the dead letter channel should handle (and ignore) any new exception thrown while sending" + + " the exchange to the dead letter endpoint. Set to false to propagate the new exception back," + + " which is useful with transactions so the transaction can detect the failure and rollback.") private String deadLetterHandleNewException; public DeadLetterChannelDefinition() { diff --git a/core/camel-core-model/src/main/java/org/apache/camel/model/errorhandler/DefaultErrorHandlerDefinition.java b/core/camel-core-model/src/main/java/org/apache/camel/model/errorhandler/DefaultErrorHandlerDefinition.java index 78934c2a20a2..39ca9c03bb4c 100644 --- a/core/camel-core-model/src/main/java/org/apache/camel/model/errorhandler/DefaultErrorHandlerDefinition.java +++ b/core/camel-core-model/src/main/java/org/apache/camel/model/errorhandler/DefaultErrorHandlerDefinition.java @@ -64,38 +64,59 @@ public class DefaultErrorHandlerDefinition extends BaseErrorHandlerDefinition { @XmlElement private RedeliveryPolicyDefinition redeliveryPolicy; @XmlAttribute - @Metadata(javaType = "java.lang.Boolean") + @Metadata(javaType = "java.lang.Boolean", + description = "If enabled, uses the original input message (body and headers) when the exchange is moved" + + " to the dead letter queue after all redelivery attempts have been exhausted." + + " Cannot be used together with useOriginalBody.") private String useOriginalMessage; @XmlAttribute - @Metadata(javaType = "java.lang.Boolean") + @Metadata(javaType = "java.lang.Boolean", + description = "If enabled, uses the original input message body (but not headers) when the exchange is moved" + + " to the dead letter queue after all redelivery attempts have been exhausted." + + " This allows enriching the message with custom headers while keeping the original body." + + " Cannot be used together with useOriginalMessage.") private String useOriginalBody; @XmlAttribute - @Metadata(label = "advanced", javaType = "org.apache.camel.processor.errorhandler.RedeliveryPolicy") + @Metadata(label = "advanced", javaType = "org.apache.camel.processor.errorhandler.RedeliveryPolicy", + description = "Sets a reference to a redelivery policy to lookup in the registry to be used.") private String redeliveryPolicyRef; @XmlAttribute - @Metadata(label = "advanced") + @Metadata(label = "advanced", + description = "Sets a reference to a logger to use for logging error handler activity.") private String loggerRef; @XmlAttribute @Metadata(label = "advanced", javaType = "org.apache.camel.LoggingLevel", defaultValue = "ERROR", - enums = "TRACE,DEBUG,INFO,WARN,ERROR,OFF") + enums = "TRACE,DEBUG,INFO,WARN,ERROR,OFF", + description = "The logging level to use when logging caught exceptions.") private String level; @XmlAttribute - @Metadata(label = "advanced") + @Metadata(label = "advanced", + description = "Name of the logger to use by the error handler.") private String logName; @XmlAttribute - @Metadata(label = "advanced", javaType = "org.apache.camel.Processor") + @Metadata(label = "advanced", javaType = "org.apache.camel.Processor", + description = "Sets a reference to a processor that is invoked before each redelivery attempt." + + " Can be used to change the exchange before it is redelivered.") private String onRedeliveryRef; @XmlAttribute - @Metadata(label = "advanced", javaType = "org.apache.camel.Processor") + @Metadata(label = "advanced", javaType = "org.apache.camel.Processor", + description = "Sets a reference to a processor that is invoked just after an exception occurred." + + " Can be used to perform custom logging. Any exception thrown from this processor is ignored.") private String onExceptionOccurredRef; @XmlAttribute - @Metadata(label = "advanced", javaType = "org.apache.camel.Processor") + @Metadata(label = "advanced", javaType = "org.apache.camel.Processor", + description = "Sets a reference to a processor to prepare the exchange before handled by the failure" + + " processor or dead letter channel. This allows for example to enrich the message before" + + " sending to a dead letter queue.") private String onPrepareFailureRef; @XmlAttribute - @Metadata(label = "advanced", javaType = "org.apache.camel.Processor") + @Metadata(label = "advanced", javaType = "org.apache.camel.Processor", + description = "Sets a reference to a retry while predicate." + + " Redelivery continues as long as the predicate evaluates to true.") private String retryWhileRef; @XmlAttribute - @Metadata(label = "advanced", javaType = "java.util.concurrent.ScheduledExecutorService") + @Metadata(label = "advanced", javaType = "java.util.concurrent.ScheduledExecutorService", + description = "Sets a reference to a thread pool to be used for asynchronous redelivery.") private String executorServiceRef; public DefaultErrorHandlerDefinition() {
