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 5f496955e056 CAMEL-23535: camel-api - batches 16-20: enhance
class-level Javadoc for REST, tooling, properties, exchange, and root-package
types (#24098)
5f496955e056 is described below
commit 5f496955e05663e3f560e5b8dd9427658eadd8a2
Author: Adriano Machado <[email protected]>
AuthorDate: Thu Jun 18 01:40:56 2026 -0400
CAMEL-23535: camel-api - batches 16-20: enhance class-level Javadoc for
REST, tooling, properties, exchange, and root-package types (#24098)
* CAMEL-23535: camel-api - batch 16: enhance class-level Javadoc for REST
SPIs
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* CAMEL-23535: camel-api - batch 17: enhance class-level Javadoc for CLI
and model-dumper SPIs
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* CAMEL-23535: camel-api - batch 18: enhance class-level Javadoc for
properties, language, and resolver SPIs
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* CAMEL-23535: camel-api - batch 19: enhance class-level Javadoc for
exchange processing SPIs
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* CAMEL-23535: camel-api - batch 20: enhance class-level Javadoc for
root-package exception and utility types
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
---------
Co-authored-by: Claude Sonnet 4.6 <[email protected]>
---
.../apache/camel/NoFactoryAvailableException.java | 13 ++++++++++++-
.../java/org/apache/camel/NoSuchBeanException.java | 13 ++++++++++++-
.../org/apache/camel/SSLContextParametersAware.java | 16 +++++++++++++++-
.../main/java/org/apache/camel/StaticService.java | 14 +++++++++++++-
.../java/org/apache/camel/spi/CliConnector.java | 12 +++++++++++-
.../org/apache/camel/spi/CliConnectorFactory.java | 12 ++++++++++--
.../org/apache/camel/spi/DataFormatResolver.java | 12 +++++++++++-
.../org/apache/camel/spi/HeadersMapFactory.java | 14 ++++++++++++--
.../org/apache/camel/spi/InflightRepository.java | 15 ++++++++++++++-
.../main/java/org/apache/camel/spi/Language.java | 19 ++++++++++++++++---
.../java/org/apache/camel/spi/LanguageResolver.java | 12 +++++++++++-
.../org/apache/camel/spi/LifecycleStrategy.java | 16 +++++++++++++++-
.../org/apache/camel/spi/ModelToJavaDumper.java | 14 +++++++++++++-
.../java/org/apache/camel/spi/ModelToXMLDumper.java | 16 +++++++++++++++-
.../org/apache/camel/spi/ModelToYAMLDumper.java | 16 +++++++++++++++-
.../org/apache/camel/spi/PropertiesComponent.java | 21 +++++++++++++++++++--
.../org/apache/camel/spi/PropertiesFunction.java | 14 +++++++++++++-
.../apache/camel/spi/RestApiConsumerFactory.java | 18 ++++++++++++++----
.../camel/spi/RestBindingJaxbDataFormatFactory.java | 12 +++++++++++-
.../org/apache/camel/spi/RestConfiguration.java | 19 ++++++++++++++++---
.../org/apache/camel/spi/RestProducerFactory.java | 16 ++++++++++++++--
.../java/org/apache/camel/spi/RestRegistry.java | 16 ++++++++++++++--
.../org/apache/camel/spi/RouteTopologyDumper.java | 15 ++++++++++++++-
.../org/apache/camel/spi/RoutesBuilderLoader.java | 11 ++++++++++-
.../main/java/org/apache/camel/spi/UnitOfWork.java | 21 +++++++++++++++++++--
.../org/apache/camel/spi/UnitOfWorkFactory.java | 17 ++++++++++++-----
26 files changed, 351 insertions(+), 43 deletions(-)
diff --git
a/core/camel-api/src/main/java/org/apache/camel/NoFactoryAvailableException.java
b/core/camel-api/src/main/java/org/apache/camel/NoFactoryAvailableException.java
index feb77c7c0023..7ed45b884439 100644
---
a/core/camel-api/src/main/java/org/apache/camel/NoFactoryAvailableException.java
+++
b/core/camel-api/src/main/java/org/apache/camel/NoFactoryAvailableException.java
@@ -20,7 +20,18 @@ import java.io.IOException;
import java.util.Objects;
/**
- * Thrown if no factory resource is available for the given URI
+ * Thrown by the Camel {@code FactoryFinder} mechanism when no implementation
class can be located for a given service
+ * URI.
+ * <p/>
+ * The {@code FactoryFinder} scans the classpath for service descriptor files
under
+ * {@code META-INF/services/org/apache/camel/} to discover pluggable
implementations of Camel SPIs (components, data
+ * formats, languages, dumpers, etc.). When the required JAR is absent from
the classpath, or when the service
+ * descriptor file is missing or misconfigured, this exception is thrown with
the full service URI that could not be
+ * resolved. It extends {@link java.io.IOException} so callers that use the
raw I/O-based discovery path can catch it at
+ * the right level; higher-level Camel code typically wraps it in a {@link
RuntimeCamelException} for propagation across
+ * unchecked API boundaries.
+ *
+ * @see RuntimeCamelException
*/
public class NoFactoryAvailableException extends IOException {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/NoSuchBeanException.java
b/core/camel-api/src/main/java/org/apache/camel/NoSuchBeanException.java
index 6d15ef558c71..f02c11069283 100644
--- a/core/camel-api/src/main/java/org/apache/camel/NoSuchBeanException.java
+++ b/core/camel-api/src/main/java/org/apache/camel/NoSuchBeanException.java
@@ -21,7 +21,18 @@ import java.util.Objects;
import org.jspecify.annotations.Nullable;
/**
- * A runtime exception if a given bean could not be found in the {@link
org.apache.camel.spi.Registry}
+ * Thrown when a bean cannot be found in the Camel {@link
org.apache.camel.spi.Registry} by name or by type.
+ * <p/>
+ * Raised by registry lookup methods such as
+ * {@link org.apache.camel.CamelContext#getRegistry()}{@code
.lookupByName(String)},
+ * {@link org.apache.camel.CamelContext#getRegistry()}{@code
.lookupByNameAndType(String, Class)}, the bean component,
+ * and the bean language when a referenced bean is absent or when more than
one bean matches a given name (ambiguous
+ * match). Route authors encountering this exception should verify that the
required module is on the classpath and that
+ * the bean name in the DSL matches exactly the name under which the bean was
registered. The constructor variants
+ * cover: name only, name with ambiguous count, name with expected type, and
name with root cause.
+ *
+ * @see org.apache.camel.spi.Registry
+ * @see RuntimeCamelException
*/
public class NoSuchBeanException extends RuntimeCamelException {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/SSLContextParametersAware.java
b/core/camel-api/src/main/java/org/apache/camel/SSLContextParametersAware.java
index 597510a52ebe..a53f3dc556e2 100644
---
a/core/camel-api/src/main/java/org/apache/camel/SSLContextParametersAware.java
+++
b/core/camel-api/src/main/java/org/apache/camel/SSLContextParametersAware.java
@@ -20,7 +20,21 @@ import org.apache.camel.support.jsse.SSLContextParameters;
import org.jspecify.annotations.Nullable;
/**
- * Indicates that an object is able to use the global {@link
SSLContextParameters} if configured.
+ * Marker interface for Camel components and endpoints that can consume the
context-wide
+ * {@link org.apache.camel.support.jsse.SSLContextParameters} configured on
the {@link CamelContext}.
+ * <p/>
+ * Camel supports a single global SSL/TLS configuration via
+ * {@link
CamelContext#setSSLContextParameters(org.apache.camel.support.jsse.SSLContextParameters)}.
Components that
+ * implement this interface expose the {@link
#isUseGlobalSslContextParameters()} /
+ * {@link #setUseGlobalSslContextParameters(boolean)} pair; when enabled,
{@link #retrieveGlobalSslContextParameters()}
+ * fetches the context-level instance so the component does not need its own
per-endpoint TLS configuration. This
+ * pattern avoids duplicating keystore and truststore settings across many
endpoints while still allowing per-endpoint
+ * overrides when the component has its own {@code SSLContextParameters}
property.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/camel-configuration-utilities.html";>JSSE
Utility</a> in the Camel user
+ * manual.
+ *
+ * @see org.apache.camel.support.jsse.SSLContextParameters
*/
public interface SSLContextParametersAware extends CamelContextAware {
diff --git a/core/camel-api/src/main/java/org/apache/camel/StaticService.java
b/core/camel-api/src/main/java/org/apache/camel/StaticService.java
index 68ac0dd7e6b1..e77682c3687c 100644
--- a/core/camel-api/src/main/java/org/apache/camel/StaticService.java
+++ b/core/camel-api/src/main/java/org/apache/camel/StaticService.java
@@ -17,7 +17,19 @@
package org.apache.camel;
/**
- * Marker for indicating the {@link Service} is a static service (only one
instance per {@link CamelContext}).
+ * Marker interface indicating that a {@link Service} is a "static" service: a
singleton within a {@link CamelContext}
+ * that is created once at context startup and shared for the context lifetime.
+ * <p/>
+ * Static services are managed differently from ordinary services: the context
starts and stops them as part of its own
+ * lifecycle rather than per-route or per-endpoint lifecycle. Examples include
+ * {@link org.apache.camel.spi.PropertiesComponent}, {@link
org.apache.camel.spi.RestRegistry},
+ * {@link org.apache.camel.spi.InflightRepository}, and other context-wide
infrastructure services. A service that
+ * implements this marker will not be started or stopped multiple times even
if multiple routes reference it — the
+ * context guarantees exactly one start and one stop across its full lifecycle.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/lifecycle.html";>Lifecycle</a>
in the Camel user manual.
+ *
+ * @see Service
*/
public interface StaticService extends Service {
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/CliConnector.java
b/core/camel-api/src/main/java/org/apache/camel/spi/CliConnector.java
index 3f09890bb162..caadbe6d5b2e 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/CliConnector.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/CliConnector.java
@@ -20,8 +20,18 @@ import org.apache.camel.NonManagedService;
import org.apache.camel.StaticService;
/**
- * Local {@link CliConnector} that allows Camel CLI to manage local running
Camel integrations.
+ * SPI that exposes a Camel integration to the Camel CLI for local inspection
and control.
+ * <p/>
+ * An implementation is created by {@link CliConnectorFactory} and added as a
{@link org.apache.camel.Service} to the
+ * {@link org.apache.camel.CamelContext} lifecycle. Once started, it opens a
local communication channel (typically a
+ * platform-specific named pipe or unix-domain socket) that the {@code camel}
CLI process attaches to for commands such
+ * as {@code camel get}, {@code camel top}, {@code camel trace}, and {@code
camel stop}. The {@link #sigterm()} method
+ * is invoked when the CLI requests a graceful shutdown; {@link
#updateDelay(int)} allows the CLI to tune the
+ * connector's internal poll frequency.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/camel-jbang.html";>Camel CLI
(JBang)</a> in the Camel user manual.
*
+ * @see CliConnectorFactory
* @since 3.19
*/
public interface CliConnector extends StaticService, NonManagedService {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/CliConnectorFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/CliConnectorFactory.java
index 651a349d78e5..1ed5593b9c37 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/CliConnectorFactory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/CliConnectorFactory.java
@@ -19,10 +19,18 @@ package org.apache.camel.spi;
import org.apache.camel.Service;
/**
- * Factory for creating connector to CLI tooling.
+ * SPI factory for creating a {@link CliConnector} that enables Camel CLI
management of a live integration.
* <p/>
- * Such as a local {@link CliConnector} that allows Camel CLI to manage local
running Camel integrations.
+ * The factory is discovered via the service key {@link #FACTORY} using {@code
FactoryFinder} when the
+ * {@code camel-cli-connector} module is on the classpath. At startup, {@link
org.apache.camel.CamelContext} calls
+ * {@link #createConnector()} and registers the returned connector as a
managed {@link org.apache.camel.Service}. The
+ * factory also carries runtime metadata (platform name, version, main class)
that the CLI uses to identify the
+ * integration process: {@link #setRuntime(String)} / {@link #getRuntime()},
{@link #setRuntimeVersion(String)} /
+ * {@link #getRuntimeVersion()}, and {@link #setRuntimeStartClass(String)} /
{@link #getRuntimeStartClass()}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/camel-jbang.html";>Camel CLI
(JBang)</a> in the Camel user manual.
*
+ * @see CliConnector
* @since 3.19
*/
public interface CliConnectorFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/DataFormatResolver.java
b/core/camel-api/src/main/java/org/apache/camel/spi/DataFormatResolver.java
index aa8aa4cbf912..8254f35ba0cd 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/DataFormatResolver.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/DataFormatResolver.java
@@ -20,7 +20,17 @@ import org.apache.camel.CamelContext;
import org.jspecify.annotations.Nullable;
/**
- * Represents a resolver of data formats.
+ * SPI strategy for resolving a {@link DataFormat} implementation by name.
+ * <p/>
+ * The default implementation first checks the Camel {@link Registry} for a
bean registered under the data format name,
+ * then falls back to classpath service files under {@code
META-INF/services/org/apache/camel/dataformat/}. Each call to
+ * {@link #createDataFormat(String, org.apache.camel.CamelContext)} returns a
fresh, non-shared instance because data
+ * formats carry per-invocation state. Custom resolvers can alias format
names, wrap the resolved instance with
+ * decorators, or source formats from a non-classpath registry.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/data-format.html";>Data
Format</a> in the Camel user manual.
+ *
+ * @see DataFormat
*/
public interface DataFormatResolver {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/HeadersMapFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/HeadersMapFactory.java
index 5463052b9699..19c38d72a451 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/HeadersMapFactory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/HeadersMapFactory.java
@@ -21,9 +21,19 @@ import java.util.Map;
import org.apache.camel.Message;
/**
- * Factory to create the {@link Map} implementation to use for storing headers
on {@link Message}.
+ * SPI factory that creates the {@link java.util.Map} implementation used to
store headers on a {@link Message}.
+ * <p/>
+ * The factory is discovered via the service key {@link #FACTORY}. The default
implementation
+ * ({@code DefaultHeadersMapFactory} in {@code camel-base-engine}) returns a
case-insensitive linked hash map, which is
+ * important for HTTP-style protocols where header names such as {@code
content-type} and {@code Content-Type} must be
+ * treated as equal. An alternative implementation ({@code
FastHeadersMapFactory} in {@code camel-headersmap}) provides
+ * higher-throughput concurrent access. Custom implementations must correctly
implement
+ * {@link #isInstanceOf(java.util.Map)} (so Camel can detect whether a given
map was created by this factory) and
+ * {@link #newMap(java.util.Map)} (defensive copy semantics for {@link
Message#setHeaders}).
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/exchange.html";>Exchange</a> in
the Camel user manual.
*
- * @see org.apache.camel.impl.engine.DefaultHeadersMapFactory
+ * @see Message
*/
public interface HeadersMapFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/InflightRepository.java
b/core/camel-api/src/main/java/org/apache/camel/spi/InflightRepository.java
index 046ac36f9a7e..a203252439ea 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/InflightRepository.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/InflightRepository.java
@@ -23,7 +23,20 @@ import org.apache.camel.StaticService;
import org.jspecify.annotations.Nullable;
/**
- * A repository which tracks in flight {@link Exchange}s.
+ * A live registry that tracks every {@link org.apache.camel.Exchange} that is
currently being processed within the
+ * {@link org.apache.camel.CamelContext}.
+ * <p/>
+ * The routing engine calls {@link #add(org.apache.camel.Exchange)} when an
exchange enters processing and
+ * {@link #remove(org.apache.camel.Exchange)} when it completes (successfully
or with failure). Per-route counts are
+ * available via {@link #size(String)}; the full list of inflight exchanges is
accessible via {@link #browse()}, which
+ * returns {@link InflightExchange} snapshots with elapsed-time and duration
metrics.
+ * {@link org.apache.camel.spi.ShutdownStrategy} polls this repository to wait
until the inflight count reaches zero
+ * before completing a graceful shutdown. The JMX management layer and
developer console expose the inflight data for
+ * operational visibility.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/graceful-shutdown.html";>Graceful
Shutdown</a> in the Camel user manual.
+ *
+ * @see ShutdownStrategy
*/
public interface InflightRepository extends StaticService {
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/Language.java
b/core/camel-api/src/main/java/org/apache/camel/spi/Language.java
index 6e9464b75b13..53495336f0f8 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/Language.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/Language.java
@@ -20,10 +20,23 @@ import org.apache.camel.Expression;
import org.apache.camel.Predicate;
/**
- * Represents a language to be used for creating {@link Expression} or {@link
Predicate} instances.
+ * SPI base for every Camel expression and predicate language.
* <p/>
- * Languages are resolved by name via the {@link
org.apache.camel.CamelContext#resolveLanguage(String)} method.
- * Implementations must be thread-safe as expressions and predicates may be
evaluated concurrently.
+ * Implementations include {@code simple}, {@code groovy}, {@code jexl},
{@code mvel}, {@code xpath}, {@code jsonpath},
+ * {@code spel}, and many others. They are resolved by name via
+ * {@link org.apache.camel.CamelContext#resolveLanguage(String)}, which first
checks the Camel registry and then falls
+ * back to the classpath service loader at
+ * {@link LanguageResolver#resolveLanguage(String,
org.apache.camel.CamelContext)}. The two core factory methods —
+ * {@link #createExpression(String)} and {@link #createPredicate(String)} —
accept a text expression and return a
+ * thread-safe, reusable instance. The overloaded {@code Object[]} variants
allow passing pre-parsed language-specific
+ * options (e.g., XPath namespace maps or tokenizer delimiters) to avoid
repeated parsing overhead. All implementations
+ * must be thread-safe because expressions and predicates are evaluated
concurrently on multiple exchanges.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/languages.html";>Languages</a>
in the Camel user manual.
+ *
+ * @see LanguageResolver
+ * @see org.apache.camel.Expression
+ * @see org.apache.camel.Predicate
*/
public interface Language {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/LanguageResolver.java
b/core/camel-api/src/main/java/org/apache/camel/spi/LanguageResolver.java
index 5eed1f56800c..f0f8d0238957 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/LanguageResolver.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/LanguageResolver.java
@@ -20,7 +20,17 @@ import org.apache.camel.CamelContext;
import org.apache.camel.NoSuchLanguageException;
/**
- * A pluggable strategy for resolving different languages in a loosely coupled
manner
+ * SPI strategy for resolving a {@link Language} implementation by name in a
loosely coupled way.
+ * <p/>
+ * The default implementation first checks the Camel {@link Registry} for a
bean registered under the language name,
+ * then falls back to the classpath service files under {@code
META-INF/services/org/apache/camel/language/}. Custom
+ * resolvers can alias language names, redirect to a different implementation,
or integrate with a non-classpath
+ * language registry. Multiple resolvers can be registered on {@link
org.apache.camel.CamelContext}; they are tried in
+ * priority order until one returns a non-null result or {@link
org.apache.camel.NoSuchLanguageException} is thrown.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/languages.html";>Languages</a>
in the Camel user manual.
+ *
+ * @see Language
*/
public interface LanguageResolver {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/LifecycleStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/LifecycleStrategy.java
index 037e7e585c70..32553c954f1c 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/LifecycleStrategy.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/LifecycleStrategy.java
@@ -29,7 +29,21 @@ import org.apache.camel.VetoCamelContextStartException;
import org.jspecify.annotations.Nullable;
/**
- * Strategy for lifecycle notifications.
+ * Observer SPI that receives callbacks for every significant lifecycle event
in a
+ * {@link org.apache.camel.CamelContext}.
+ * <p/>
+ * Callbacks cover the full lifecycle of the context itself (initializing,
starting, started, stopping, stopped), plus
+ * every {@link org.apache.camel.Component}, {@link
org.apache.camel.Endpoint}, {@link org.apache.camel.Route}, and
+ * {@link org.apache.camel.Service} that is added, started, stopped, or
removed. Thread pool creation and shutdown are
+ * also notified. Multiple strategies can be registered via
+ * {@link
org.apache.camel.CamelContext#addLifecycleStrategy(LifecycleStrategy)}. The JMX
management layer
+ * ({@link ManagementStrategy}) is the primary built-in implementor; it
registers and unregisters MBeans in response to
+ * lifecycle events. Implementations may throw {@link
org.apache.camel.VetoCamelContextStartException} from
+ * {@link #onContextInitializing} to prevent context startup.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/lifecycle.html";>Lifecycle</a>
in the Camel user manual.
+ *
+ * @see ManagementStrategy
*/
public interface LifecycleStrategy {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ModelToJavaDumper.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ModelToJavaDumper.java
index c8080cd1e19b..3d76721f7217 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ModelToJavaDumper.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ModelToJavaDumper.java
@@ -20,8 +20,20 @@ import org.apache.camel.CamelContext;
import org.apache.camel.NamedNode;
/**
- * SPI for dumping model definitions into Java DSL representation.
+ * SPI that serialises Camel route model definitions to their Java DSL
representation (source code).
+ * <p/>
+ * The implementation is provided by {@code camel-java-io} and discovered via
the service key {@link #FACTORY}. Callers
+ * supply a {@link org.apache.camel.CamelContext} and a {@link
org.apache.camel.NamedNode} route definition; the dumper
+ * returns a formatted Java source string. The overloaded
+ * {@link #dumpModelAsJava(org.apache.camel.CamelContext,
org.apache.camel.NamedNode, boolean, boolean) dumpModelAsJava}
+ * variant adds control over placeholder resolution and auto-generated ID
inclusion. The primary consumers are
+ * {@code camel-jbang} export commands that convert running integrations into
a Java DSL project.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/camel-jbang.html";>Camel CLI
(camel-jbang)</a> for the export commands
+ * that use this dumper.
*
+ * @see ModelToXMLDumper
+ * @see ModelToYAMLDumper
* @since 4.21
*/
public interface ModelToJavaDumper {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ModelToXMLDumper.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ModelToXMLDumper.java
index 329906cb6279..abd5e1caca18 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ModelToXMLDumper.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ModelToXMLDumper.java
@@ -23,8 +23,22 @@ import org.apache.camel.CamelContext;
import org.apache.camel.NamedNode;
/**
- * SPI for dumping model definitions into XML representation.
+ * SPI that serialises Camel route model definitions to their XML DSL
representation.
+ * <p/>
+ * The implementation is provided by {@code camel-xml-io} and discovered via
the service key {@link #FACTORY}. Callers
+ * supply a {@link org.apache.camel.CamelContext} and a {@link
org.apache.camel.NamedNode} route definition; the dumper
+ * returns a formatted XML string. The overloaded
+ * {@link #dumpModelAsXml(org.apache.camel.CamelContext,
org.apache.camel.NamedNode, boolean, boolean, boolean)
+ * dumpModelAsXml} variant adds control over placeholder resolution,
auto-generated ID inclusion, and source-location
+ * metadata. Separate methods handle bean definitions and global data-format
definitions. The primary consumers are
+ * {@code camel-jbang} export commands, the developer console, and {@link
org.apache.camel.CamelContext} route-dump
+ * helpers.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/camel-jbang.html";>Camel CLI
(camel-jbang)</a> for the export commands
+ * that use this dumper.
*
+ * @see ModelToYAMLDumper
+ * @see ModelToJavaDumper
* @since 3.1
*/
public interface ModelToXMLDumper {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ModelToYAMLDumper.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ModelToYAMLDumper.java
index 7983f4d35d79..bd24782a13f5 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ModelToYAMLDumper.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ModelToYAMLDumper.java
@@ -23,8 +23,22 @@ import org.apache.camel.CamelContext;
import org.apache.camel.NamedNode;
/**
- * SPI for dumping model definitions into YAML representation.
+ * SPI that serialises Camel route model definitions to their YAML DSL
representation.
+ * <p/>
+ * The implementation is provided by {@code camel-yaml-io} and discovered via
the service key {@link #FACTORY}. Callers
+ * supply a {@link org.apache.camel.CamelContext} and a {@link
org.apache.camel.NamedNode} route definition; the dumper
+ * returns a formatted YAML string. The overloaded
+ * {@link #dumpModelAsYaml(org.apache.camel.CamelContext,
org.apache.camel.NamedNode, boolean, boolean, boolean, boolean)
+ * dumpModelAsYaml} variant adds control over placeholder resolution, URI
expansion into key-value parameters,
+ * auto-generated ID inclusion, and source-location metadata. Separate methods
handle bean definitions and global
+ * data-format definitions. The primary consumers are {@code camel-jbang}
export commands, the developer console, and
+ * {@link org.apache.camel.CamelContext} route-dump helpers.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/camel-jbang.html";>Camel CLI
(camel-jbang)</a> for the export commands
+ * that use this dumper.
*
+ * @see ModelToXMLDumper
+ * @see ModelToJavaDumper
* @since 4.0
*/
public interface ModelToYAMLDumper {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesComponent.java
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesComponent.java
index 250731b7128a..9aa55bddc93c 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesComponent.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesComponent.java
@@ -28,8 +28,25 @@ import org.apache.camel.StaticService;
import org.jspecify.annotations.Nullable;
/**
- * Component for property placeholders and loading properties from sources
(such as .properties file from classpath or
- * file system)
+ * SPI for the Camel property-placeholder subsystem, which resolves {@code
{{key}}} tokens in endpoint URIs, DSL
+ * expressions, and configuration values.
+ * <p/>
+ * An implementation is obtained via {@link
org.apache.camel.CamelContext#getPropertiesComponent()} and is discovered at
+ * startup via the service key {@link #FACTORY}. Property values are sourced
from one or more {@link PropertiesSource}
+ * implementations (classpath {@code .properties} files, environment
variables, system properties, and cloud-vault
+ * integrations such as AWS Secrets Manager and HashiCorp Vault) and merged in
priority order. Custom prefix-based
+ * resolution is supported via {@link PropertiesFunction} instances registered
with
+ * {@link #addPropertiesFunction(PropertiesFunction)}; they handle tokens of
the form {@code {{name:remainder}}} and
+ * power the built-in {@code env:}, {@code sys:}, and {@code secret:}
functions.
+ * <p/>
+ * Three scoped property layers allow test isolation without touching the
shared properties file: override properties
+ * (highest priority), initial properties, and thread-local properties.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/using-propertyplaceholder.html";>Using
Property Placeholder</a> in the
+ * Camel user manual.
+ *
+ * @see PropertiesSource
+ * @see PropertiesFunction
*/
public interface PropertiesComponent extends StaticService {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesFunction.java
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesFunction.java
index d312349e35ac..331f1c9b281c 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesFunction.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesFunction.java
@@ -17,8 +17,20 @@
package org.apache.camel.spi;
/**
- * A function that is applied instead of looking up a property placeholder.
+ * Extension point for the {@link PropertiesComponent} that handles property
placeholders of the form
+ * {@code {{name:remainder}}}, where {@code name} matches {@link #getName()}.
+ * <p/>
+ * Functions are registered with {@link
PropertiesComponent#addPropertiesFunction(PropertiesFunction)} and are tried
+ * before (or after, depending on {@link #lookupFirst(String)}) the normal
property-source lookup chain. The
+ * {@link #apply(String)} method receives the part after the colon separator
and returns the resolved value. Built-in
+ * functions include {@code env:} (environment variables), {@code sys:}
(system properties), and {@code secret:} (cloud
+ * vault lookups). Custom functions can implement arbitrary resolution logic,
such as decrypting encrypted values,
+ * fetching from a database, or generating dynamic tokens.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/using-propertyplaceholder.html";>Using
Property Placeholder</a> in the
+ * Camel user manual.
*
+ * @see PropertiesComponent
* @since 3.3
*/
public interface PropertiesFunction {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/RestApiConsumerFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RestApiConsumerFactory.java
index 66beeccfeec6..071042d15623 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/RestApiConsumerFactory.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/RestApiConsumerFactory.java
@@ -23,11 +23,21 @@ import org.apache.camel.Consumer;
import org.apache.camel.Processor;
/**
- * Allows SPI to plugin a {@link RestApiConsumerFactory} that creates the
Camel {@link Consumer} responsible for
- * handling incoming HTTP GET requests from clients that request to access the
REST API documentation.
+ * SPI that creates the Camel {@link org.apache.camel.Consumer} responsible
for handling incoming HTTP GET requests to
+ * the REST API documentation endpoint.
* <p/>
- * For example most of the Camel components that supports REST-DSL does that,
such as <tt>camel-jetty</tt>,
- * <tt>camel-netty-http</tt>.
+ * When a REST-DSL route includes an {@code apiContextPath} in its {@link
RestConfiguration}, Camel uses this factory to
+ * create a dedicated consumer that serves the in-memory OpenAPI specification
generated from the route model. HTTP
+ * components that support the REST DSL (such as {@code camel-jetty}, {@code
camel-netty-http}, and
+ * {@code camel-platform-http}) implement this interface alongside {@link
RestConsumerFactory}. The factory is distinct
+ * from {@link RestOpenApiConsumerFactory}, which handles full contract-first
OpenAPI spec routing rather than just
+ * serving the generated doc listing.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/rest-dsl.html";>Rest DSL</a> in
the Camel user manual.
+ *
+ * @see RestConsumerFactory
+ * @see RestOpenApiConsumerFactory
+ * @see RestConfiguration
*/
public interface RestApiConsumerFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/RestBindingJaxbDataFormatFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RestBindingJaxbDataFormatFactory.java
index c7755f01666c..090235367806 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/RestBindingJaxbDataFormatFactory.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/RestBindingJaxbDataFormatFactory.java
@@ -20,8 +20,18 @@ import org.apache.camel.CamelContext;
import org.jspecify.annotations.Nullable;
/**
- * SPI for setting up XML data format (JAXB) for rest-dsl.
+ * SPI that configures a JAXB {@link DataFormat} pair for XML binding in the
Camel REST DSL.
+ * <p/>
+ * When a REST-DSL route uses a binding mode that includes XML (e.g. {@link
RestConfiguration.RestBindingMode#xml} or
+ * {@link RestConfiguration.RestBindingMode#json_xml}), the REST binding
processor calls {@link #setupJaxb setupJaxb()}
+ * to obtain configured {@link DataFormat} instances for the input and output
types. This interface decouples the REST
+ * binding layer in {@code camel-core} from the {@code camel-jaxb} module: the
factory is discovered via the service key
+ * {@link #FACTORY} and is only invoked when JAXB binding is actually needed,
so routes that use JSON-only binding do
+ * not require {@code camel-jaxb} on the classpath.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/rest-dsl.html";>Rest DSL</a> in
the Camel user manual.
*
+ * @see RestConfiguration
* @since 3.2
*/
public interface RestBindingJaxbDataFormatFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/RestConfiguration.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RestConfiguration.java
index f965a1133ec0..05e8d01a514b 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/RestConfiguration.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/RestConfiguration.java
@@ -22,9 +22,22 @@ import java.util.Objects;
import org.jspecify.annotations.Nullable;
/**
- * Configuration use by {@link org.apache.camel.spi.RestConsumerFactory} and
- * {@link org.apache.camel.spi.RestApiConsumerFactory} for Camel components to
support the Camel
- * {@link org.apache.camel.model.rest.RestDefinition rest} DSL.
+ * Central configuration bean for the Camel REST DSL, shared by {@link
RestConsumerFactory},
+ * {@link RestProducerFactory}, and {@link RestApiConsumerFactory}
implementations.
+ * <p/>
+ * An instance of this class is held on {@link org.apache.camel.CamelContext}
and controls every aspect of REST service
+ * hosting and client invocation: the HTTP component to use (e.g. {@code
platform-http}, {@code jetty},
+ * {@code netty-http}, {@code servlet}), the server host and port, the binding
mode ({@link RestBindingMode#off},
+ * {@link RestBindingMode#json}, {@link RestBindingMode#xml}, or {@link
RestBindingMode#json_xml}), CORS headers, JSON
+ * and XML data-format class names, and additional {@code Map<String, Object>}
property overrides for the component,
+ * consumer, and producer tiers. The configuration is typically expressed via
the {@code restConfiguration()} builder in
+ * the Java DSL, or the {@code rest-configuration} element in XML and YAML
DSLs.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/rest-dsl.html";>Rest DSL</a> in
the Camel user manual.
+ *
+ * @see RestConsumerFactory
+ * @see RestProducerFactory
+ * @see RestRegistry
*/
public class RestConfiguration {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/RestProducerFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RestProducerFactory.java
index 2430217633cb..ab9b0b2c8f6b 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/RestProducerFactory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/RestProducerFactory.java
@@ -23,8 +23,20 @@ import org.apache.camel.Producer;
import org.jspecify.annotations.Nullable;
/**
- * Allows SPI to plugin a {@link RestProducerFactory} that creates the Camel
{@link Producer} responsible for performing
- * HTTP requests to call a remote REST service.
+ * SPI that creates the Camel {@link org.apache.camel.Producer} responsible
for performing HTTP requests to call a
+ * remote REST service.
+ * <p/>
+ * Implementations are provided by HTTP-capable Camel components such as
{@code camel-http}, {@code camel-netty-http},
+ * and {@code camel-vertx-http}. At runtime, {@link
org.apache.camel.CamelContext} selects the active implementation
+ * from the registry using the producer component name configured in {@link
RestConfiguration}. The single
+ * {@link #createProducer} method receives the full invocation contract:
target host (scheme:host:port), HTTP verb, base
+ * path, URI template, query parameters, accepted and produced media types,
the shared {@link RestConfiguration}, and
+ * any additional component-specific parameters.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/rest-dsl.html";>Rest DSL</a> in
the Camel user manual.
+ *
+ * @see RestConsumerFactory
+ * @see RestConfiguration
*/
public interface RestProducerFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/RestRegistry.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RestRegistry.java
index 8dbb5a539304..e7794d7f670f 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/RestRegistry.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/RestRegistry.java
@@ -23,8 +23,20 @@ import org.apache.camel.StaticService;
import org.jspecify.annotations.Nullable;
/**
- * A registry of all REST services running within the {@link
org.apache.camel.CamelContext} which have been defined and
- * created using the <a href="https://camel.apache.org/rest-dsl";>Rest DSL</a>.
+ * A live registry of all REST services running within the {@link
org.apache.camel.CamelContext} that were defined using
+ * the Camel REST DSL.
+ * <p/>
+ * Each REST-DSL route registers its verb-plus-path pair at startup via {@link
#addRestService addRestService()}; the
+ * registry keeps a {@link RestService} record per operation that carries the
URL, HTTP method, media types, binding
+ * types, and hit counter. The developer console, JMX management layer, and
the {@code camel-openapi-java} module all
+ * query this registry to render live service listings and to generate the
OpenAPI specification
+ * ({@link #apiDocAsJson()}). Separately, OpenAPI contract entries are tracked
as "specifications" via
+ * {@link #addRestSpecification addRestSpecification()}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/rest-dsl.html";>Rest DSL</a> in
the Camel user manual.
+ *
+ * @see RestConsumerFactory
+ * @see RestConfiguration
*/
public interface RestRegistry extends StaticService {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/RouteTopologyDumper.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RouteTopologyDumper.java
index 68d6a6d5407b..3a436f219b65 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/RouteTopologyDumper.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/RouteTopologyDumper.java
@@ -21,8 +21,21 @@ import java.util.List;
import org.apache.camel.CamelContext;
/**
- * SPI for computing inter-route topology, showing how routes connect to each
other through shared endpoints.
+ * SPI that analyses the active Camel routes and computes a graph describing
how they interconnect through shared
+ * endpoints.
+ * <p/>
+ * The implementation is discovered via the service key {@link #FACTORY}. The
single
+ * {@link #dumpTopology(org.apache.camel.CamelContext)} method returns a
{@link TopologyResult} record containing:
+ * {@link TopologyNode} entries (one per route, classified as {@code route} or
{@code trigger}), {@link TopologyEdge}
+ * entries (connections between two routes via a shared endpoint URI,
classified as {@code internal} for direct/seda or
+ * {@code external} for remote transports), and {@link
TopologyExternalEndpoint} entries (remote systems a route talks
+ * to). The developer console uses this output to render an interactive route
graph.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/camel-jbang.html";>Camel CLI
(camel-jbang)</a> for the developer console
+ * that renders this graph.
*
+ * @see ModelToXMLDumper
+ * @see ModelToYAMLDumper
* @since 4.21
*/
public interface RouteTopologyDumper {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/RoutesBuilderLoader.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RoutesBuilderLoader.java
index 241462d161c8..af292c7db875 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/RoutesBuilderLoader.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/RoutesBuilderLoader.java
@@ -21,8 +21,17 @@ import org.apache.camel.RoutesBuilder;
import org.apache.camel.StaticService;
/**
- * SPI for loading {@link RoutesBuilder} from a {@link Resource}.
+ * SPI that loads {@link org.apache.camel.RoutesBuilder} instances from a
{@link Resource} identified by file extension.
+ * <p/>
+ * Implementations are keyed by the extension they support (e.g. {@code java},
{@code xml}, {@code yaml}, {@code kts})
+ * and are discovered at path {@link #FACTORY_PATH}. At startup, {@link
org.apache.camel.CamelContext} iterates over the
+ * configured route resource locations, selects the appropriate loader via
{@link #isSupportedExtension(String)}, and
+ * calls {@link #loadRoutesBuilder(Resource)} to obtain one or more {@link
org.apache.camel.RoutesBuilder}s that are
+ * then added to the context. Before routes are loaded, {@link
#preParseRoute(Resource)} may be called to extract
+ * {@code camel.main.*} bootstrap configuration from the DSL source without
fully loading the routes; this allows the
+ * context to apply route-shaping settings (e.g. component overrides) before
the full load.
*
+ * @see Resource
* @since 3.8
*/
public interface RoutesBuilderLoader extends StaticService, CamelContextAware {
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/UnitOfWork.java
b/core/camel-api/src/main/java/org/apache/camel/spi/UnitOfWork.java
index 6ecb73bd25d0..99870ee8c594 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/UnitOfWork.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/UnitOfWork.java
@@ -26,8 +26,25 @@ import org.apache.camel.Route;
import org.jspecify.annotations.Nullable;
/**
- * An object representing the unit of work processing an {@link Exchange}
which allows the use of
- * {@link Synchronization} hooks. This object might map one-to-one with a
transaction in JPA or Spring; or might not.
+ * Tracks the lifecycle of a single {@link org.apache.camel.Exchange} as it
flows through the routing engine, and
+ * provides hooks for {@link Synchronization} callbacks and async continuation
coordination.
+ * <p/>
+ * A {@code UnitOfWork} instance is created per exchange by {@link
UnitOfWorkFactory} and attached to it for the
+ * exchange's entire lifetime. It accumulates {@link Synchronization} objects
(via
+ * {@link #addSynchronization(Synchronization)}); these callbacks fire {@code
onComplete} or {@code onFailure} when the
+ * exchange finishes, regardless of whether it was processed synchronously or
across multiple async threads. The unit
+ * also holds the current {@link org.apache.camel.Route} context, breadcrumb
ID, and — in conjunction with
+ * {@link CamelMDCService} — carries MDC values across continuation threads so
that log entries on async threads retain
+ * the same correlation keys. The relationship to a JPA or Spring transaction
is intentionally loose: the unit of work
+ * may span multiple transactions, or a single transaction may span multiple
units of work.
+ * <p/>
+ * Most production code should extend {@code DefaultUnitOfWork} from {@code
camel-base-engine} rather than implement
+ * this interface directly. See {@link UnitOfWorkFactory} for details on
plugging in a custom impl.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/exchange.html";>Exchange</a> in
the Camel user manual.
+ *
+ * @see UnitOfWorkFactory
+ * @see Synchronization
*/
public interface UnitOfWork {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/UnitOfWorkFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/UnitOfWorkFactory.java
index 51d2651a2041..dc17677a6414 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/UnitOfWorkFactory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/UnitOfWorkFactory.java
@@ -21,12 +21,19 @@ import org.apache.camel.CamelContext;
import org.apache.camel.Exchange;
/**
- * Factory to create {@link org.apache.camel.spi.UnitOfWork}.
+ * SPI factory that creates a {@link UnitOfWork} for each incoming {@link
org.apache.camel.Exchange}.
+ * <p/>
+ * The factory is called by the routing engine at exchange creation time; the
returned {@link UnitOfWork} is attached to
+ * the exchange for its lifetime. Implementing a custom factory is only
necessary for very rare use-cases such as
+ * integrating with an external transaction manager or attaching custom
synchronization hooks globally. The created
+ * {@link UnitOfWork} <b>must</b> extend {@code DefaultUnitOfWork} from {@code
camel-base-engine}: that class wires the
+ * breadcrumb ID, MDC propagation, and route-context tracking that the routing
engine relies on. Implementing
+ * {@link UnitOfWork} from scratch without extending {@code DefaultUnitOfWork}
will break async routing and MDC logging
+ * in subtle ways.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/exchange.html";>Exchange</a> in
the Camel user manual.
*
- * <b>IMPORTANT:</b> Implementing a custom {@link UnitOfWorkFactory} is only
intended for very rare and special
- * use-cases. The created {@link UnitOfWork} is highly recommended to extend
- * org.apache.camel.impl.engine.DefaultUnitOfWork to ensure Camel
functionality works correctly during routing of
- * {@link Exchange}s.
+ * @see UnitOfWork
*/
public interface UnitOfWorkFactory extends AfterPropertiesConfigured {
