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 eb634cbd92fc CAMEL-23535: camel-api - batches 5+6: enhance class-level
Javadoc for annotations, bean binding, and expressions (#23740)
eb634cbd92fc is described below
commit eb634cbd92fca48c43a3024235337381151c72c7
Author: Adriano Machado <[email protected]>
AuthorDate: Fri Jun 5 11:46:36 2026 -0400
CAMEL-23535: camel-api - batches 5+6: enhance class-level Javadoc for
annotations, bean binding, and expressions (#23740)
Batch 5 - Bean binding annotations and injection:
- Body: add bean-binding context and @see links
- Header: add named-header injection context and @see links
- Headers: add all-headers map use case and @see links
- ExchangeProperty: explain exchange vs message namespace, add @see links
- ExchangeProperties: distinguish from @ExchangeProperty, add @see links
- Variable: add variables user-manual link and bean-binding context
- Variables: add variables user-manual link, distinguish from @Variable
- VariableAware: explain variables store contract and framework use
- Handler: clarify method-selection disambiguation, add @see links
- BeanInject: expand registry lookup description, add @see links
- BeanConfigInject: explain property-prefix binding mechanism, add @see
links
- EndpointConsumerResolver: explain from()-clause use case, add @see links
- EndpointProducerResolver: explain to()-clause use case, add @see links
Batch 6 - Expressions, predicates, type conversion:
- ExpressionFactory: describe deferred/lazy factory pattern,
@FunctionalInterface note
- PredicateFactory: same as ExpressionFactory, @see cross-reference
- StaticExpression: explain constant-value optimization and startup
resolution
- TimeoutMap: describe eviction mechanism and internal use cases
Comment-only change: no signatures, behavior, or runtime code altered.
Signed-off-by: Adriano Machado <[email protected]>
Co-authored-by: Claude Sonnet 4.6 <[email protected]>
---
.../src/main/java/org/apache/camel/BeanConfigInject.java | 11 +++++++++--
.../camel-api/src/main/java/org/apache/camel/BeanInject.java | 12 ++++++++++--
core/camel-api/src/main/java/org/apache/camel/Body.java | 11 ++++++++++-
.../main/java/org/apache/camel/EndpointConsumerResolver.java | 8 +++++++-
.../main/java/org/apache/camel/EndpointProducerResolver.java | 8 +++++++-
.../src/main/java/org/apache/camel/ExchangeProperties.java | 8 +++++++-
.../src/main/java/org/apache/camel/ExchangeProperty.java | 11 +++++++++--
.../src/main/java/org/apache/camel/ExpressionFactory.java | 9 ++++++++-
core/camel-api/src/main/java/org/apache/camel/Handler.java | 12 ++++++++++--
core/camel-api/src/main/java/org/apache/camel/Header.java | 9 ++++++++-
core/camel-api/src/main/java/org/apache/camel/Headers.java | 9 ++++++++-
.../src/main/java/org/apache/camel/PredicateFactory.java | 9 ++++++++-
.../src/main/java/org/apache/camel/StaticExpression.java | 9 ++++++++-
.../camel-api/src/main/java/org/apache/camel/TimeoutMap.java | 11 ++++++++++-
core/camel-api/src/main/java/org/apache/camel/Variable.java | 9 ++++++++-
.../src/main/java/org/apache/camel/VariableAware.java | 9 ++++++++-
core/camel-api/src/main/java/org/apache/camel/Variables.java | 8 +++++++-
.../src/main/java/org/apache/camel/spi/UuidGenerator.java | 4 ++--
18 files changed, 144 insertions(+), 23 deletions(-)
diff --git
a/core/camel-api/src/main/java/org/apache/camel/BeanConfigInject.java
b/core/camel-api/src/main/java/org/apache/camel/BeanConfigInject.java
index 845c2049d12e..ef7182ec37c1 100644
--- a/core/camel-api/src/main/java/org/apache/camel/BeanConfigInject.java
+++ b/core/camel-api/src/main/java/org/apache/camel/BeanConfigInject.java
@@ -23,9 +23,16 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Used to indicate an injection point of a configuration bean (obtained from
the {@link org.apache.camel.spi.Registry},
- * or a new instance is created) into a POJO.
+ * Marks a field, method, constructor, or parameter as an injection point for
a configuration bean.
+ * <p/>
+ * {@link #value()} specifies the root property prefix (e.g. {@code
camel.component.mycomp}). During bean
+ * post-processing Camel first looks for an existing instance in the {@link
org.apache.camel.spi.Registry}; if none is
+ * found it creates a new instance of the declared type and binds all matching
properties from that prefix using Camel's
+ * property-binding mechanism. This is the standard way to inject typed
configuration objects into components and custom
+ * services.
*
+ * @see BeanInject
+ * @see PropertyInject
* @since 3.2
*/
@Retention(RetentionPolicy.RUNTIME)
diff --git a/core/camel-api/src/main/java/org/apache/camel/BeanInject.java
b/core/camel-api/src/main/java/org/apache/camel/BeanInject.java
index 43defcea9e26..54baff681352 100644
--- a/core/camel-api/src/main/java/org/apache/camel/BeanInject.java
+++ b/core/camel-api/src/main/java/org/apache/camel/BeanInject.java
@@ -23,9 +23,17 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Used to indicate an injection point of a bean obtained from the {@link
org.apache.camel.spi.Registry}, into a POJO.
+ * Marks a field, method, constructor, or parameter as an injection point for
a bean obtained from the Camel
+ * <a href="https://camel.apache.org/manual/registry.html";>{@link
org.apache.camel.spi.Registry}</a>.
+ * <p/>
+ * When Camel performs bean post-processing it resolves the injection by
looking up the registry: by name if
+ * {@link #value()} is set, or by type if no name is provided. The resolved
bean is then injected at the annotated site.
+ * If no matching bean is found an exception is thrown at startup.
*
- * If no name is specified then the lookup is anonymous and based on lookup up
by the type.
+ * @see BeanConfigInject
+ * @see PropertyInject
+ * @see BindToRegistry
+ * @since 3.2
*/
@Retention(RetentionPolicy.RUNTIME)
@Documented
diff --git a/core/camel-api/src/main/java/org/apache/camel/Body.java
b/core/camel-api/src/main/java/org/apache/camel/Body.java
index 76e026b2f8c3..d8d2346da260 100644
--- a/core/camel-api/src/main/java/org/apache/camel/Body.java
+++ b/core/camel-api/src/main/java/org/apache/camel/Body.java
@@ -23,7 +23,16 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Marks a parameter as being the body of an inbound {@link Message}
+ * Marks a method parameter as the payload of the inbound {@link Message} when
Camel performs
+ * <a href="https://camel.apache.org/manual/bean-binding.html";>bean
binding</a>.
+ * <p/>
+ * When a bean method is invoked via the Bean EIP or {@link Consume}, Camel
maps the exchange to the method parameters.
+ * A parameter annotated with {@code @Body} receives {@link
Message#getBody()}, optionally converted to the declared
+ * parameter type via the {@link TypeConverter} infrastructure.
+ *
+ * @see Header
+ * @see Headers
+ * @see ExchangeProperty
*/
@Retention(RetentionPolicy.RUNTIME)
@Documented
diff --git
a/core/camel-api/src/main/java/org/apache/camel/EndpointConsumerResolver.java
b/core/camel-api/src/main/java/org/apache/camel/EndpointConsumerResolver.java
index 98711c07af6c..3dee12f8645c 100644
---
a/core/camel-api/src/main/java/org/apache/camel/EndpointConsumerResolver.java
+++
b/core/camel-api/src/main/java/org/apache/camel/EndpointConsumerResolver.java
@@ -17,8 +17,14 @@
package org.apache.camel;
/**
- * An interface to represent an object that can be resolved as a consumer
{@link Endpoint}
+ * Implemented by objects that can be resolved to a consumer-facing {@link
Endpoint}.
+ * <p/>
+ * The DSL and annotation processor call {@link #resolve(CamelContext)} to
obtain a concrete {@link Endpoint} when an
+ * object used in a {@code from()} clause is not itself an endpoint URI
string. This allows richer types (for example,
+ * enum constants or wrapper objects) to be used as route input descriptors
without requiring string parsing.
*
+ * @see EndpointProducerResolver
+ * @see Endpoint
* @since 3.1
*/
public interface EndpointConsumerResolver {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/EndpointProducerResolver.java
b/core/camel-api/src/main/java/org/apache/camel/EndpointProducerResolver.java
index 770451cd5f32..e02e0d031cb8 100644
---
a/core/camel-api/src/main/java/org/apache/camel/EndpointProducerResolver.java
+++
b/core/camel-api/src/main/java/org/apache/camel/EndpointProducerResolver.java
@@ -17,8 +17,14 @@
package org.apache.camel;
/**
- * An interface to represent an object that can be resolved as a producer
{@link Endpoint}
+ * Implemented by objects that can be resolved to a producer-facing {@link
Endpoint}.
+ * <p/>
+ * The DSL and annotation processor call {@link #resolve(CamelContext)} to
obtain a concrete {@link Endpoint} when an
+ * object used in a {@code to()} clause is not itself an endpoint URI string.
This allows richer types (for example,
+ * enum constants or wrapper objects) to be used as route destinations without
requiring string parsing.
*
+ * @see EndpointConsumerResolver
+ * @see Endpoint
* @since 3.1
*/
public interface EndpointProducerResolver {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/ExchangeProperties.java
b/core/camel-api/src/main/java/org/apache/camel/ExchangeProperties.java
index 67dcfd9e042d..8aa8ac52ae1b 100644
--- a/core/camel-api/src/main/java/org/apache/camel/ExchangeProperties.java
+++ b/core/camel-api/src/main/java/org/apache/camel/ExchangeProperties.java
@@ -23,8 +23,14 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Marks a parameter as being an injection point of the exchange properties of
an {@link Exchange}
+ * Marks a method parameter as the entire exchange-property map of the current
{@link Exchange} when Camel performs
+ * <a href="https://camel.apache.org/manual/bean-binding.html";>bean
binding</a>.
+ * <p/>
+ * The parameter type should be {@code Map<String, Object>} (or a compatible
super-type). Unlike
+ * {@link ExchangeProperty}, which injects a single named property, {@code
@ExchangeProperties} gives the method direct
+ * access to all exchange properties at once.
*
+ * @see ExchangeProperty
* @see Exchange#getProperties()
*/
@Retention(RetentionPolicy.RUNTIME)
diff --git
a/core/camel-api/src/main/java/org/apache/camel/ExchangeProperty.java
b/core/camel-api/src/main/java/org/apache/camel/ExchangeProperty.java
index 84129c7f8d62..d206b36f2492 100644
--- a/core/camel-api/src/main/java/org/apache/camel/ExchangeProperty.java
+++ b/core/camel-api/src/main/java/org/apache/camel/ExchangeProperty.java
@@ -23,9 +23,16 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Marks a parameter as being an injection point of a property of an {@link
org.apache.camel.Exchange}
+ * Marks a method parameter as a named exchange property when Camel performs
+ * <a href="https://camel.apache.org/manual/bean-binding.html";>bean
binding</a>.
+ * <p/>
+ * Exchange properties are key-value pairs stored on the {@link Exchange} (not
on the {@link Message}), surviving across
+ * multiple processing steps for the lifetime of the exchange. They are
typically used for internal routing state and
+ * correlation data. The {@link #value()} attribute names the property to
inject; the value is converted to the declared
+ * parameter type via the {@link TypeConverter} infrastructure.
*
- * @see org.apache.camel.Exchange#getProperty(String)
+ * @see ExchangeProperties
+ * @see Exchange#getProperty(String)
*/
@Retention(RetentionPolicy.RUNTIME)
@Documented
diff --git
a/core/camel-api/src/main/java/org/apache/camel/ExpressionFactory.java
b/core/camel-api/src/main/java/org/apache/camel/ExpressionFactory.java
index 82523db49979..0ef30ecfc39c 100644
--- a/core/camel-api/src/main/java/org/apache/camel/ExpressionFactory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/ExpressionFactory.java
@@ -17,8 +17,15 @@
package org.apache.camel;
/**
- * A factory for creating {@link Expression}
+ * Deferred factory for creating an {@link Expression} within a {@link
CamelContext}.
+ * <p/>
+ * Being a {@link FunctionalInterface}, implementations are typically supplied
as lambdas or method references wherever
+ * a context-aware expression must be constructed lazily, for example when
wiring EIP definitions during route startup.
+ * The factory receives the context so it can resolve language services,
registries, or configuration values needed to
+ * build the expression.
*
+ * @see Expression
+ * @see PredicateFactory
* @since 3.0
*/
@FunctionalInterface
diff --git a/core/camel-api/src/main/java/org/apache/camel/Handler.java
b/core/camel-api/src/main/java/org/apache/camel/Handler.java
index 5a9843a436a7..e1b9aada39de 100644
--- a/core/camel-api/src/main/java/org/apache/camel/Handler.java
+++ b/core/camel-api/src/main/java/org/apache/camel/Handler.java
@@ -23,8 +23,16 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Marks a method on a POJO as being the preferred method to invoke when Camel
looks for methods to invoke using the
- * {@link org.apache.camel.component.bean.BeanEndpoint BeanEndpoint}.
+ * Marks a method on a bean as the preferred handler for
+ * <a href="https://camel.apache.org/manual/bean-binding.html";>bean
binding</a>.
+ * <p/>
+ * When Camel invokes a bean via the Bean EIP or {@link Consume} and the bean
has multiple public methods, it uses
+ * heuristics to select the best match. Annotating exactly one method with
{@code @Handler} short-circuits that
+ * selection: Camel always calls the annotated method without ambiguity checks
or reflection-based scoring. Only one
+ * method per class should carry this annotation.
+ *
+ * @see Consume
+ * @see Body
*/
@Retention(RetentionPolicy.RUNTIME)
@Documented
diff --git a/core/camel-api/src/main/java/org/apache/camel/Header.java
b/core/camel-api/src/main/java/org/apache/camel/Header.java
index 49b357dc7bdc..d893d788a52f 100644
--- a/core/camel-api/src/main/java/org/apache/camel/Header.java
+++ b/core/camel-api/src/main/java/org/apache/camel/Header.java
@@ -23,8 +23,15 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Marks a parameter as being a header on an inbound {@link Message}
+ * Marks a method parameter as a named header from the inbound {@link Message}
when Camel performs
+ * <a href="https://camel.apache.org/manual/bean-binding.html";>bean
binding</a>.
+ * <p/>
+ * The {@link #value()} attribute names the header to inject. Camel converts
the header value to the declared parameter
+ * type via the {@link TypeConverter} infrastructure. If the header is absent
the parameter receives {@code null} (or
+ * the primitive default).
*
+ * @see Body
+ * @see Headers
* @see Message#getHeader(String)
*/
@Retention(RetentionPolicy.RUNTIME)
diff --git a/core/camel-api/src/main/java/org/apache/camel/Headers.java
b/core/camel-api/src/main/java/org/apache/camel/Headers.java
index c9d15744fa24..9a1d584db8ab 100644
--- a/core/camel-api/src/main/java/org/apache/camel/Headers.java
+++ b/core/camel-api/src/main/java/org/apache/camel/Headers.java
@@ -23,8 +23,15 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Marks a parameter as being an injection point of the headers of an inbound
{@link Message}
+ * Marks a method parameter as the entire header map of the inbound {@link
Message} when Camel performs
+ * <a href="https://camel.apache.org/manual/bean-binding.html";>bean
binding</a>.
+ * <p/>
+ * The parameter type should be {@code Map<String, Object>} (or a compatible
super-type). Unlike {@link Header}, which
+ * injects a single named header, {@code @Headers} gives the method direct
access to all headers at once, useful when
+ * the set of headers to process is dynamic or unknown at compile time.
*
+ * @see Header
+ * @see Body
* @see Message#getHeaders()
*/
@Retention(RetentionPolicy.RUNTIME)
diff --git
a/core/camel-api/src/main/java/org/apache/camel/PredicateFactory.java
b/core/camel-api/src/main/java/org/apache/camel/PredicateFactory.java
index 4c7de7b8772a..76e076a0fa59 100644
--- a/core/camel-api/src/main/java/org/apache/camel/PredicateFactory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/PredicateFactory.java
@@ -17,8 +17,15 @@
package org.apache.camel;
/**
- * A factory for creating {@link Predicate}
+ * Deferred factory for creating a {@link Predicate} within a {@link
CamelContext}.
+ * <p/>
+ * Being a {@link FunctionalInterface}, implementations are typically supplied
as lambdas or method references wherever
+ * a context-aware predicate must be constructed lazily, for example when
wiring filter or choice EIP definitions during
+ * route startup. The factory receives the context so it can resolve language
services or configuration values needed to
+ * build the predicate.
*
+ * @see Predicate
+ * @see ExpressionFactory
* @since 3.8
*/
@FunctionalInterface
diff --git
a/core/camel-api/src/main/java/org/apache/camel/StaticExpression.java
b/core/camel-api/src/main/java/org/apache/camel/StaticExpression.java
index 889b5d46f838..fc552230da63 100644
--- a/core/camel-api/src/main/java/org/apache/camel/StaticExpression.java
+++ b/core/camel-api/src/main/java/org/apache/camel/StaticExpression.java
@@ -19,8 +19,15 @@ package org.apache.camel;
import org.jspecify.annotations.Nullable;
/**
- * Marked if the {@link Expression} or {@link Predicate} is based from a
constant value (ie is static).
+ * Marker for an {@link Expression} whose value is a compile-time or
configuration-time constant.
+ * <p/>
+ * A static expression always evaluates to the same result regardless of the
{@link Exchange}, so the framework can
+ * optimize it: it is evaluated once, the result is cached, and no
per-exchange evaluation overhead is incurred.
+ * Implementations must expose the constant through {@link #getValue()} and
allow it to be overwritten via
+ * {@link #setValue(Object)} (for example, when a property placeholder is
resolved at startup).
*
+ * @see Expression
+ * @see Predicate
* @since 3.7
*/
public interface StaticExpression extends Expression {
diff --git a/core/camel-api/src/main/java/org/apache/camel/TimeoutMap.java
b/core/camel-api/src/main/java/org/apache/camel/TimeoutMap.java
index 726b4c3e2a49..89c176c733ec 100644
--- a/core/camel-api/src/main/java/org/apache/camel/TimeoutMap.java
+++ b/core/camel-api/src/main/java/org/apache/camel/TimeoutMap.java
@@ -19,7 +19,16 @@ package org.apache.camel;
import org.jspecify.annotations.Nullable;
/**
- * Represents a map of values which timeout after a period of inactivity.
+ * A map whose entries expire automatically after a configurable period of
inactivity.
+ * <p/>
+ * Entries are added via {@link #put(Object, Object, long)} with an individual
timeout in milliseconds. A background
+ * {@link Service} thread periodically scans the map and evicts entries whose
timeout has elapsed, notifying any
+ * registered {@link Listener}. This is used internally by components that
need session or correlation state with
+ * automatic cleanup, such as the aggregator's in-memory repository and the
idempotent consumer.
+ *
+ * @param <K> the key type
+ * @param <V> the value type
+ * @see Service
*/
public interface TimeoutMap<K, V> extends Service {
diff --git a/core/camel-api/src/main/java/org/apache/camel/Variable.java
b/core/camel-api/src/main/java/org/apache/camel/Variable.java
index d1d583d55051..b690e23c70d8 100644
--- a/core/camel-api/src/main/java/org/apache/camel/Variable.java
+++ b/core/camel-api/src/main/java/org/apache/camel/Variable.java
@@ -23,8 +23,15 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Marks a parameter as being a variable
+ * Marks a method parameter as a named <a
href="https://camel.apache.org/manual/variables.html";>variable</a> when Camel
+ * performs <a href="https://camel.apache.org/manual/bean-binding.html";>bean
binding</a>.
+ * <p/>
+ * Variables are an exchange-scoped store (separate from headers and exchange
properties) introduced in Camel 4.4 to
+ * provide a cleaner namespace for application data that should not pollute
message headers. The {@link #value()}
+ * attribute names the variable to inject; the value is converted to the
declared parameter type via the
+ * {@link TypeConverter} infrastructure.
*
+ * @see Variables
* @see Exchange#getVariable(String)
* @since 4.4
*/
diff --git a/core/camel-api/src/main/java/org/apache/camel/VariableAware.java
b/core/camel-api/src/main/java/org/apache/camel/VariableAware.java
index de3feb836277..f1ec8df657db 100644
--- a/core/camel-api/src/main/java/org/apache/camel/VariableAware.java
+++ b/core/camel-api/src/main/java/org/apache/camel/VariableAware.java
@@ -19,8 +19,15 @@ package org.apache.camel;
import org.jspecify.annotations.Nullable;
/**
- * An interface to represent an object that supports variables.
+ * Implemented by objects that carry a <a
href="https://camel.apache.org/manual/variables.html";>variables</a> store.
+ * <p/>
+ * Variables are a key-value namespace on the {@link Exchange} (separate from
message headers and exchange properties)
+ * introduced in Camel 4.4. This interface is the read/write contract for that
store and is used internally by the
+ * framework and by EIP implementations that need to get or set variables
programmatically.
*
+ * @see Variable
+ * @see Variables
+ * @see Exchange
* @since 4.4
*/
public interface VariableAware {
diff --git a/core/camel-api/src/main/java/org/apache/camel/Variables.java
b/core/camel-api/src/main/java/org/apache/camel/Variables.java
index baa987b7efde..d33c7c5ecbd7 100644
--- a/core/camel-api/src/main/java/org/apache/camel/Variables.java
+++ b/core/camel-api/src/main/java/org/apache/camel/Variables.java
@@ -23,8 +23,14 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Marks a parameter as being an injection point of the variables
+ * Marks a method parameter as the entire <a
href="https://camel.apache.org/manual/variables.html";>variables</a> map of
+ * the current {@link Exchange} when Camel performs <a
href="https://camel.apache.org/manual/bean-binding.html";>bean
+ * binding</a>.
+ * <p/>
+ * The parameter type should be {@code Map<String, Object>} (or a compatible
super-type). Unlike {@link Variable}, which
+ * injects a single named variable, {@code @Variables} gives the method direct
access to all variables at once.
*
+ * @see Variable
* @see Exchange#getVariables()
* @since 4.4
*/
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/UuidGenerator.java
b/core/camel-api/src/main/java/org/apache/camel/spi/UuidGenerator.java
index a80ce18ebafe..f9e1c4422e35 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/UuidGenerator.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/UuidGenerator.java
@@ -22,14 +22,14 @@ package org.apache.camel.spi;
public interface UuidGenerator {
/**
- * Generates an UUID string representation.
+ * Generates a UUID string representation.
*
* @return the unique id.
*/
String generateUuid();
/**
- * Generates an UUID string representation to be used as exchange id.
+ * Generates a UUID string representation to be used as exchange id.
*
* @return the unique exchange id
*/
