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 060f16e091b5 CAMEL-23535: camel-api - enhance class-level javadoc for
messaging core types (#23330)
060f16e091b5 is described below
commit 060f16e091b52c342dd9cba2d8c3b337b0dba62a
Author: Adriano Machado <[email protected]>
AuthorDate: Tue May 19 11:35:08 2026 -0400
CAMEL-23535: camel-api - enhance class-level javadoc for messaging core
types (#23330)
Batch 2: Exchange, ExchangeExtension, ExchangePattern, ExchangePropertyKey,
Message, MessageHistory, StreamCache, WrappedFile, RuntimeExchangeException,
InvalidPayloadException, InvalidPayloadRuntimeException,
NoSuchHeaderException,
NoSuchHeaderOrPropertyException, NoSuchPropertyException,
NoTypeConversionAvailableException, TypeConversionException,
RollbackExchangeException, ValidationException.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
rh-pre-commit.version: 2.3.2
rh-pre-commit.check-secrets: ENABLED
---
.../src/main/java/org/apache/camel/Exchange.java | 5 +++++
.../main/java/org/apache/camel/ExchangeExtension.java | 17 +++++++++++------
.../src/main/java/org/apache/camel/ExchangePattern.java | 11 ++++++++++-
.../main/java/org/apache/camel/ExchangePropertyKey.java | 7 ++++++-
.../java/org/apache/camel/InvalidPayloadException.java | 8 +++++++-
.../apache/camel/InvalidPayloadRuntimeException.java | 9 ++++++++-
.../src/main/java/org/apache/camel/Message.java | 3 +++
.../src/main/java/org/apache/camel/MessageHistory.java | 10 +++++++++-
.../java/org/apache/camel/NoSuchHeaderException.java | 7 ++++++-
.../apache/camel/NoSuchHeaderOrPropertyException.java | 8 ++++++++
.../java/org/apache/camel/NoSuchPropertyException.java | 6 +++++-
.../camel/NoTypeConversionAvailableException.java | 8 +++++++-
.../org/apache/camel/RollbackExchangeException.java | 9 ++++++++-
.../java/org/apache/camel/RuntimeExchangeException.java | 8 +++++++-
.../src/main/java/org/apache/camel/StreamCache.java | 2 ++
.../java/org/apache/camel/TypeConversionException.java | 7 ++++++-
.../main/java/org/apache/camel/ValidationException.java | 8 +++++---
.../src/main/java/org/apache/camel/WrappedFile.java | 10 +++++++++-
18 files changed, 122 insertions(+), 21 deletions(-)
diff --git a/core/camel-api/src/main/java/org/apache/camel/Exchange.java
b/core/camel-api/src/main/java/org/apache/camel/Exchange.java
index dd51776756f1..9240f08444c1 100644
--- a/core/camel-api/src/main/java/org/apache/camel/Exchange.java
+++ b/core/camel-api/src/main/java/org/apache/camel/Exchange.java
@@ -47,6 +47,11 @@ import org.jspecify.annotations.Nullable;
* To access or modify the current message, use the {@link #getMessage()}
method. Camel uses {@link #getMessage()} to
* obtain the current message during routing. If a {@link Processor} modifies
the message, those changes are visible to
* subsequent processors. The {@link ExchangePattern} determines whether a
reply is expected (InOut) or not (InOnly).
+ *
+ * @see Message
+ * @see ExchangePattern
+ * @see ExchangeExtension
+ * @see Processor
*/
@ConstantProvider("org.apache.camel.ExchangeConstantProvider")
public interface Exchange extends VariableAware {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/ExchangeExtension.java
b/core/camel-api/src/main/java/org/apache/camel/ExchangeExtension.java
index d92de664a556..03977e1032f2 100644
--- a/core/camel-api/src/main/java/org/apache/camel/ExchangeExtension.java
+++ b/core/camel-api/src/main/java/org/apache/camel/ExchangeExtension.java
@@ -24,12 +24,17 @@ import org.apache.camel.spi.Synchronization;
import org.apache.camel.spi.UnitOfWork;
import org.jspecify.annotations.Nullable;
-/*
- * {@link Exchange} extensions which contains the methods and APIs that are
not intended for Camel end users but
- * used internally by Camel for optimization purposes, SPI, custom components,
or more advanced used-cases with
- * Camel.
- *
- * @since 4.0
+/**
+ * Internal extension surface of {@link Exchange} exposing methods and APIs
not intended for Camel end users, but used
+ * inside Camel for optimization, SPI integration, custom component
development, and advanced use cases.
+ * <p/>
+ * An instance is obtained by calling {@link Exchange#getExchangeExtension()}.
+ * <p/>
+ * The contract of this interface may change between minor releases without
the usual deprecation cycle that applies to
+ * the main {@link Exchange} API.
+ *
+ * @see Exchange
+ * @since 4.0
*/
public interface ExchangeExtension {
diff --git a/core/camel-api/src/main/java/org/apache/camel/ExchangePattern.java
b/core/camel-api/src/main/java/org/apache/camel/ExchangePattern.java
index 7c5a15030fa6..638368323275 100644
--- a/core/camel-api/src/main/java/org/apache/camel/ExchangePattern.java
+++ b/core/camel-api/src/main/java/org/apache/camel/ExchangePattern.java
@@ -20,7 +20,16 @@ import jakarta.xml.bind.annotation.XmlEnum;
import jakarta.xml.bind.annotation.XmlType;
/**
- * Represents the kind of message exchange pattern
+ * The message exchange pattern of an {@link Exchange}, indicating whether the
caller expects a reply.
+ * <p/>
+ * {@link #InOnly} is used for fire-and-forget messaging: the caller sends a
message and does not wait for a response.
+ * {@link #InOut} is used for request-reply messaging: the caller sends a
message and blocks until a response is
+ * received.
+ * <p/>
+ * The pattern is set on the {@link Exchange} and is checked by the Camel
routing engine and endpoints to determine how
+ * to handle the interaction.
+ *
+ * @see Exchange
*/
@XmlType
@XmlEnum
diff --git
a/core/camel-api/src/main/java/org/apache/camel/ExchangePropertyKey.java
b/core/camel-api/src/main/java/org/apache/camel/ExchangePropertyKey.java
index c488456242fb..650960c95b77 100644
--- a/core/camel-api/src/main/java/org/apache/camel/ExchangePropertyKey.java
+++ b/core/camel-api/src/main/java/org/apache/camel/ExchangePropertyKey.java
@@ -20,8 +20,13 @@ import org.apache.camel.spi.CircuitBreakerConstants;
import org.jspecify.annotations.Nullable;
/**
- * An enum of common and known keys for exchange properties used by camel-core.
+ * Typed enum of the well-known {@link Exchange} property keys used by
camel-core.
+ * <p/>
+ * Each constant wraps the corresponding {@link Exchange} string constant and
provides a type-safe alternative for
+ * reading and writing internal exchange properties via {@link
Exchange#getProperty(ExchangePropertyKey)} and
+ * {@link Exchange#setProperty(ExchangePropertyKey, Object)}.
*
+ * @see Exchange
* @since 3.9
*/
public enum ExchangePropertyKey {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/InvalidPayloadException.java
b/core/camel-api/src/main/java/org/apache/camel/InvalidPayloadException.java
index 8751f09a2310..ae65584111f1 100644
--- a/core/camel-api/src/main/java/org/apache/camel/InvalidPayloadException.java
+++ b/core/camel-api/src/main/java/org/apache/camel/InvalidPayloadException.java
@@ -21,7 +21,13 @@ import java.util.Objects;
import org.jspecify.annotations.Nullable;
/**
- * Is thrown if the payload from the exchange could not be retrieved because
of being null, wrong class type etc.
+ * Thrown when the body of a {@link Message} cannot be converted to the
expected type, for example because the body is
+ * null or its runtime type is incompatible with the requested type.
+ * <p/>
+ * This is the checked variant; for the unchecked equivalent see {@link
InvalidPayloadRuntimeException}.
+ *
+ * @see InvalidPayloadRuntimeException
+ * @see Message
*/
public class InvalidPayloadException extends CamelExchangeException {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/InvalidPayloadRuntimeException.java
b/core/camel-api/src/main/java/org/apache/camel/InvalidPayloadRuntimeException.java
index ff23c1535654..0500b829f54e 100644
---
a/core/camel-api/src/main/java/org/apache/camel/InvalidPayloadRuntimeException.java
+++
b/core/camel-api/src/main/java/org/apache/camel/InvalidPayloadRuntimeException.java
@@ -21,7 +21,14 @@ import java.util.Objects;
import org.jspecify.annotations.Nullable;
/**
- * Runtime version of the {@link InvalidPayloadException}.
+ * Unchecked variant of {@link InvalidPayloadException}, thrown when the body
of a {@link Message} cannot be converted
+ * to the expected type.
+ * <p/>
+ * Used in contexts where a checked exception is not permitted, such as inside
a {@link Processor} that calls
+ * {@link Message#getMandatoryBody(Class)}.
+ *
+ * @see InvalidPayloadException
+ * @see Message
*/
public class InvalidPayloadRuntimeException extends RuntimeExchangeException {
diff --git a/core/camel-api/src/main/java/org/apache/camel/Message.java
b/core/camel-api/src/main/java/org/apache/camel/Message.java
index e7bc4fe1d083..9f35e7fa1610 100644
--- a/core/camel-api/src/main/java/org/apache/camel/Message.java
+++ b/core/camel-api/src/main/java/org/apache/camel/Message.java
@@ -31,6 +31,9 @@ import org.jspecify.annotations.Nullable;
* implementation of the map can be configured by the {@link
HeadersMapFactory} which can be set on the
* {@link CamelContext}. The default implementation uses the {@link
org.apache.camel.util.CaseInsensitiveMap
* CaseInsensitiveMap}.
+ *
+ * @see Exchange
+ * @see ExchangePattern
*/
public interface Message {
diff --git a/core/camel-api/src/main/java/org/apache/camel/MessageHistory.java
b/core/camel-api/src/main/java/org/apache/camel/MessageHistory.java
index 46a4fd60a431..a5906fcfd36a 100644
--- a/core/camel-api/src/main/java/org/apache/camel/MessageHistory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/MessageHistory.java
@@ -19,7 +19,15 @@ package org.apache.camel;
import org.jspecify.annotations.Nullable;
/**
- * Represents the history of a Camel {@link Message} how it was routed by the
Camel routing engine.
+ * A breadcrumb record that captures the route id and processing node an
{@link Exchange} visited at a given point in
+ * time, together with the elapsed processing time at that node.
+ * <p/>
+ * History entries are accumulated in the exchange property {@link
Exchange#MESSAGE_HISTORY} when message history is
+ * enabled on the {@link CamelContext}. They are primarily used for debugging,
tracing, and performance analysis, and
+ * are surfaced via the Camel debugger and management or monitoring APIs.
+ *
+ * @see Exchange
+ * @see NamedNode
*/
public interface MessageHistory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/NoSuchHeaderException.java
b/core/camel-api/src/main/java/org/apache/camel/NoSuchHeaderException.java
index f652ae19a301..909e6f5f7955 100644
--- a/core/camel-api/src/main/java/org/apache/camel/NoSuchHeaderException.java
+++ b/core/camel-api/src/main/java/org/apache/camel/NoSuchHeaderException.java
@@ -21,9 +21,14 @@ import java.util.Objects;
import org.jspecify.annotations.Nullable;
/**
- * An exception caused when a mandatory header is not available on a message
{@link Exchange}
+ * Thrown when a mandatory header is not available on the {@link Message} of
an {@link Exchange}.
+ * <p/>
+ * Typically raised by {@link
org.apache.camel.support.ExchangeHelper#getMandatoryHeader(Exchange, String,
Class)} when
+ * a processor requires a specific header to be present.
*
* @see org.apache.camel.support.ExchangeHelper#getMandatoryHeader(Exchange,
String, Class)
+ * @see NoSuchPropertyException
+ * @see Message
*/
public class NoSuchHeaderException extends CamelExchangeException {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/NoSuchHeaderOrPropertyException.java
b/core/camel-api/src/main/java/org/apache/camel/NoSuchHeaderOrPropertyException.java
index 57d6d426d103..21feb5a796cb 100644
---
a/core/camel-api/src/main/java/org/apache/camel/NoSuchHeaderOrPropertyException.java
+++
b/core/camel-api/src/main/java/org/apache/camel/NoSuchHeaderOrPropertyException.java
@@ -21,6 +21,14 @@ import java.util.Objects;
import org.jspecify.annotations.Nullable;
/**
+ * Thrown when neither a mandatory header nor a mandatory exchange property is
available on an {@link Exchange}, and at
+ * least one of them is required for processing to continue.
+ * <p/>
+ * Combines the roles of {@link NoSuchHeaderException} and {@link
NoSuchPropertyException} for callers that accept
+ * either source but need at least one to be present.
+ *
+ * @see NoSuchHeaderException
+ * @see NoSuchPropertyException
* @since 3.18
*/
public class NoSuchHeaderOrPropertyException extends CamelExchangeException {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/NoSuchPropertyException.java
b/core/camel-api/src/main/java/org/apache/camel/NoSuchPropertyException.java
index 8efebda867dd..7535ea380748 100644
--- a/core/camel-api/src/main/java/org/apache/camel/NoSuchPropertyException.java
+++ b/core/camel-api/src/main/java/org/apache/camel/NoSuchPropertyException.java
@@ -21,9 +21,13 @@ import java.util.Objects;
import org.jspecify.annotations.Nullable;
/**
- * An exception caused when a mandatory property is not available on a message
{@link Exchange}
+ * Thrown when a mandatory exchange property is not available on an {@link
Exchange}.
+ * <p/>
+ * Typically raised by {@link
org.apache.camel.support.ExchangeHelper#getMandatoryProperty(Exchange, String,
Class)}
+ * when a processor or EIP requires a specific property to be present.
*
* @see org.apache.camel.support.ExchangeHelper#getMandatoryProperty(Exchange,
String, Class)
+ * @see NoSuchHeaderException
*/
public class NoSuchPropertyException extends CamelExchangeException {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/NoTypeConversionAvailableException.java
b/core/camel-api/src/main/java/org/apache/camel/NoTypeConversionAvailableException.java
index 262f1b72e880..ace9793095d0 100644
---
a/core/camel-api/src/main/java/org/apache/camel/NoTypeConversionAvailableException.java
+++
b/core/camel-api/src/main/java/org/apache/camel/NoTypeConversionAvailableException.java
@@ -21,7 +21,13 @@ import java.util.Objects;
import org.jspecify.annotations.Nullable;
/**
- * An exception thrown if a value could not be converted to the required type
+ * Thrown when the Camel type-converter registry cannot find a converter
capable of transforming a given value to the
+ * requested target type.
+ * <p/>
+ * This is the checked variant; for the unchecked exception raised when a
converter is found but fails during execution,
+ * see {@link TypeConversionException}.
+ *
+ * @see TypeConversionException
*/
public class NoTypeConversionAvailableException extends CamelException {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/RollbackExchangeException.java
b/core/camel-api/src/main/java/org/apache/camel/RollbackExchangeException.java
index 03dc9164238a..8141f067835e 100644
---
a/core/camel-api/src/main/java/org/apache/camel/RollbackExchangeException.java
+++
b/core/camel-api/src/main/java/org/apache/camel/RollbackExchangeException.java
@@ -19,7 +19,14 @@ package org.apache.camel;
import java.util.Objects;
/**
- * Exception used for forcing an Exchange to be rolled back.
+ * Thrown (or explicitly constructed and set on an {@link Exchange}) to signal
that the current exchange should be
+ * rolled back by the error handler.
+ * <p/>
+ * When a route uses the {@code rollback()} DSL step or a {@link Processor}
throws this exception, the Camel error
+ * handler treats it as an intentional rollback rather than an unexpected
failure. Transactional resources enlisted in
+ * the exchange's unit of work will be rolled back accordingly.
+ *
+ * @see Exchange
*/
public class RollbackExchangeException extends CamelExchangeException {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/RuntimeExchangeException.java
b/core/camel-api/src/main/java/org/apache/camel/RuntimeExchangeException.java
index a156c4fc5fcb..43645a2827a3 100644
---
a/core/camel-api/src/main/java/org/apache/camel/RuntimeExchangeException.java
+++
b/core/camel-api/src/main/java/org/apache/camel/RuntimeExchangeException.java
@@ -21,7 +21,13 @@ import java.util.Objects;
import org.jspecify.annotations.Nullable;
/**
- * A runtime exception caused by a specific message {@link Exchange}
+ * Unchecked base exception carrying the {@link Exchange} whose processing
triggered the failure.
+ * <p/>
+ * This is the unchecked counterpart of {@link CamelExchangeException} and is
the base for exceptions such as
+ * {@link InvalidPayloadRuntimeException} that are thrown in contexts where a
checked exception is not permitted.
+ *
+ * @see CamelExchangeException
+ * @see Exchange
*/
public class RuntimeExchangeException extends RuntimeCamelException {
private final transient @Nullable Exchange exchange;
diff --git a/core/camel-api/src/main/java/org/apache/camel/StreamCache.java
b/core/camel-api/src/main/java/org/apache/camel/StreamCache.java
index 289cd120cf7a..1283ffcecfdc 100644
--- a/core/camel-api/src/main/java/org/apache/camel/StreamCache.java
+++ b/core/camel-api/src/main/java/org/apache/camel/StreamCache.java
@@ -36,6 +36,8 @@ import org.jspecify.annotations.Nullable;
* <b>Important:</b> All the classes from the Camel release that implements
{@link StreamCache} is NOT intended for end
* users to create as instances, but they are part of Camels
* <a
href="https://camel.apache.org/manual/stream-caching.html";>stream-caching</a>
functionality.
+ *
+ * @see org.apache.camel.spi.StreamCachingStrategy
*/
public interface StreamCache {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/TypeConversionException.java
b/core/camel-api/src/main/java/org/apache/camel/TypeConversionException.java
index b32fa444db96..dffc82d2cb9a 100644
--- a/core/camel-api/src/main/java/org/apache/camel/TypeConversionException.java
+++ b/core/camel-api/src/main/java/org/apache/camel/TypeConversionException.java
@@ -21,7 +21,12 @@ import java.util.Objects;
import org.jspecify.annotations.Nullable;
/**
- * Exception when failing during type conversion.
+ * Unchecked exception thrown when a type converter is found but fails to
convert a value to the required type.
+ * <p/>
+ * Contrast with {@link NoTypeConversionAvailableException}, which is thrown
when no converter exists for the
+ * source-to-target type pair at all.
+ *
+ * @see NoTypeConversionAvailableException
*/
public class TypeConversionException extends RuntimeCamelException {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/ValidationException.java
b/core/camel-api/src/main/java/org/apache/camel/ValidationException.java
index f67ffda5447f..da2abe5c9e9a 100644
--- a/core/camel-api/src/main/java/org/apache/camel/ValidationException.java
+++ b/core/camel-api/src/main/java/org/apache/camel/ValidationException.java
@@ -19,9 +19,11 @@ package org.apache.camel;
import org.jspecify.annotations.Nullable;
/**
- * The base class for any validation exception, such as
- * {@link
org.apache.camel.support.processor.validation.SchemaValidationException} so
that it is easy to treat all
- * validation errors in a similar way irrespective of the particular
validation technology used.
+ * Base class for all validation exceptions, such as
+ * {@link
org.apache.camel.support.processor.validation.SchemaValidationException}, so
that callers can catch all
+ * validation failures in a single handler irrespective of the particular
validation technology used.
+ *
+ * @see Exchange
*/
public class ValidationException extends CamelExchangeException {
diff --git a/core/camel-api/src/main/java/org/apache/camel/WrappedFile.java
b/core/camel-api/src/main/java/org/apache/camel/WrappedFile.java
index 71d418fb7d13..68fa996304ef 100644
--- a/core/camel-api/src/main/java/org/apache/camel/WrappedFile.java
+++ b/core/camel-api/src/main/java/org/apache/camel/WrappedFile.java
@@ -19,7 +19,15 @@ package org.apache.camel;
import org.jspecify.annotations.Nullable;
/**
- * Wraps a file.
+ * Abstraction over a file-like object consumed by a file-oriented {@link
Consumer} (such as camel-file, camel-ftp, or
+ * camel-sftp), providing uniform access to the underlying file handle, its
content, and its length.
+ * <p/>
+ * Implementations wrap different native file types (for example {@code
java.io.File} for the local file system, or a
+ * library-specific remote file object for FTP/SFTP). The body returned by
{@link #getBody()} may be a stream, a byte
+ * array, or a string depending on the component configuration.
+ *
+ * @param <T> the native file type wrapped by this instance
+ * @see Exchange
*/
public interface WrappedFile<T> {
