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 e5380bc25421 CAMEL-23535: camel-api - batches 13-15: enhance
class-level Javadoc for management, threading, and observability SPIs (#24060)
e5380bc25421 is described below
commit e5380bc25421c357470f86d1fffbf7f08986461c
Author: Adriano Machado <[email protected]>
AuthorDate: Wed Jun 17 13:58:08 2026 -0400
CAMEL-23535: camel-api - batches 13-15: enhance class-level Javadoc for
management, threading, and observability SPIs (#24060)
* CAMEL-23535: camel-api - batch 13: enhance class-level Javadoc for
management SPIs
Adds comprehensive class-level Javadoc to the 8 JMX management SPI types in
org.apache.camel.spi: ManagementAgent, ManagementStrategy,
ManagementStrategyFactory,
ManagementNameStrategy, ManagementObjectStrategy,
ManagementObjectNameStrategy,
ManagementMBeanAssembler, and ManagementInterceptStrategy.
Each type now documents its role in the two-level management design
(strategy = high-level coordinator, agent = low-level JMX bridge), its
relationship to sibling SPIs, and links to the JMX user manual page.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* CAMEL-23535: camel-api - batch 14: enhance class-level Javadoc for
threading and scheduling SPIs
Adds comprehensive class-level Javadoc to 6 threading/scheduling SPI types:
ExecutorServiceManager, ThreadPoolProfile, ThreadPoolFactory,
BackOffTimerFactory,
ScheduledPollConsumerScheduler, and ReactiveExecutor.
Each type now documents its role in Camel's threading model, the layering
between
the high-level manager and the low-level factory, and links to the
Threading Model
user manual page.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* CAMEL-23535: camel-api - batch 15: enhance class-level Javadoc for
observability SPIs
Adds comprehensive class-level Javadoc to 5 observability SPI types:
EventNotifier, EventFactory, Tracer, CamelLogger, and CamelMDCService.
Documents the producer/consumer split between EventFactory (mints event
objects)
and EventNotifier (observes and reacts), the Tracer's before/after node
interception
model and standby mode, CamelLogger's level+marker configuration purpose,
and
CamelMDCService's role in propagating MDC across async exchange
continuations.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* CAMEL-23535: fix CamelMDCService Javadoc — correct implementation class
and module
DefaultCamelMDCService does not exist; the real implementation is
MDCService in the camel-mdc component.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
---------
Co-authored-by: Claude Sonnet 4.6 <[email protected]>
---
.../org/apache/camel/spi/BackOffTimerFactory.java | 16 +++++++++++++-
.../java/org/apache/camel/spi/CamelLogger.java | 16 +++++++++++---
.../java/org/apache/camel/spi/CamelMDCService.java | 15 ++++++++++++-
.../java/org/apache/camel/spi/EventFactory.java | 20 +++++++++++++++--
.../java/org/apache/camel/spi/EventNotifier.java | 14 +++++++++++-
.../apache/camel/spi/ExecutorServiceManager.java | 3 +++
.../java/org/apache/camel/spi/ManagementAgent.java | 19 +++++++++++++++-
.../camel/spi/ManagementInterceptStrategy.java | 19 +++++++++++++++-
.../apache/camel/spi/ManagementMBeanAssembler.java | 20 +++++++++++++++--
.../apache/camel/spi/ManagementNameStrategy.java | 25 ++++++++++++++--------
.../camel/spi/ManagementObjectNameStrategy.java | 18 +++++++++++++++-
.../apache/camel/spi/ManagementObjectStrategy.java | 18 +++++++++++++++-
.../org/apache/camel/spi/ManagementStrategy.java | 22 +++++++++++++------
.../camel/spi/ManagementStrategyFactory.java | 16 +++++++++++++-
.../org/apache/camel/spi/ReactiveExecutor.java | 16 +++++++++++++-
.../camel/spi/ScheduledPollConsumerScheduler.java | 18 +++++++++++-----
.../org/apache/camel/spi/ThreadPoolFactory.java | 20 +++++++++++++----
.../org/apache/camel/spi/ThreadPoolProfile.java | 17 +++++++++++++--
.../src/main/java/org/apache/camel/spi/Tracer.java | 18 +++++++++++++++-
19 files changed, 287 insertions(+), 43 deletions(-)
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/BackOffTimerFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/BackOffTimerFactory.java
index f91f12b1007d..1222448e3fdd 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/BackOffTimerFactory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/BackOffTimerFactory.java
@@ -21,9 +21,23 @@ import java.util.concurrent.ScheduledExecutorService;
import org.apache.camel.util.backoff.BackOffTimer;
/**
- * Factory for creating {@link BackOffTimer}.
+ * SPI factory for creating {@link org.apache.camel.util.backoff.BackOffTimer}
instances used to schedule retry or
+ * back-off tasks.
+ * <p/>
+ * A {@link org.apache.camel.util.backoff.BackOffTimer} drives retries
described by a
+ * {@link org.apache.camel.util.backoff.BackOff} policy (fixed delay,
exponential back-off, max elapsed time, etc.)
+ * using a {@link java.util.concurrent.ScheduledExecutorService} as the
underlying scheduler. Camel's
+ * {@link SupervisingRouteController} uses back-off timers to schedule route
restart attempts after failure.
+ * <p/>
+ * The two factory methods cover the common cases: obtain a timer that manages
its own scheduler via
+ * {@link #newBackOffTimer(String)}, or supply an externally managed scheduler
via
+ * {@link #newBackOffTimer(String,
java.util.concurrent.ScheduledExecutorService)} to share thread pool resources.
The
+ * timer must be started and stopped through its service lifecycle.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/threading-model.html";>Threading Model</a>
in the Camel user manual.
*
* @see org.apache.camel.util.backoff.BackOff
+ * @see SupervisingRouteController
* @since 4.13
*/
public interface BackOffTimerFactory {
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/CamelLogger.java
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelLogger.java
index 6c3e7daf1dad..7831630c7e14 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/CamelLogger.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/CamelLogger.java
@@ -27,10 +27,20 @@ import org.slf4j.Marker;
import org.slf4j.MarkerFactory;
/**
- * A logger which logs to a slf4j {@link Logger}.
+ * A configurable SLF4J logger wrapper that carries a {@link LoggingLevel} and
an optional SLF4J {@link Marker}.
* <p/>
- * The name <tt>CamelLogger</tt> has been chosen to avoid any name clash with
log kits which has a <tt>Logger</tt>
- * class.
+ * Camel components and EIPs that need to emit log output accept a {@code
CamelLogger} rather than a raw SLF4J
+ * {@link Logger} so that the log level and marker can be configured
externally (e.g., via endpoint URI or route DSL)
+ * without changing the logging code. The {@link #log(String)} method respects
the configured level and only writes if
+ * the underlying logger has that level enabled; {@link #doLog(String)} skips
the level check and always writes, which
+ * is useful when the check was already performed by the caller.
+ * <p/>
+ * The name {@code CamelLogger} was chosen to avoid a class-name clash with
the {@code Logger} class present in many
+ * older logging frameworks (Log4j 1.x, Commons Logging, etc.) that may be on
the classpath.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/logeip.html";>Log EIP</a> in
the Camel user manual.
+ *
+ * @see LoggingLevel
*/
public class CamelLogger {
private Logger log;
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelMDCService.java
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelMDCService.java
index 0e96b00a0dfe..a7c78d0614ed 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/CamelMDCService.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/CamelMDCService.java
@@ -20,7 +20,20 @@ import org.apache.camel.CamelContextAware;
import org.apache.camel.Service;
/**
- * A Camel MDC service is a factory for Mapped Diagnostic Context service.
+ * SPI that plugs a Mapped Diagnostic Context (MDC) propagation implementation
into Camel's exchange processing
+ * pipeline.
+ * <p/>
+ * SLF4J's MDC is thread-local, which means MDC values set on the originating
thread are not automatically visible on
+ * continuation threads used by Camel's async routing engine. Implementations
of this service are responsible for
+ * capturing the current MDC state when an exchange begins processing and
restoring it on each continuation thread, so
+ * that log entries produced across async boundaries carry the same contextual
key-value pairs (e.g.,
+ * {@code camel.exchangeId}, {@code camel.routeId}, custom breadcrumb values).
+ * <p/>
+ * Camel discovers the implementation via the service registry; the default
implementation is {@code MDCService} in
+ * {@code camel-mdc}. The {@link org.apache.camel.CamelContext} starts and
stops this service as part of its normal
+ * lifecycle.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/mdc-logging.html";>MDC
Logging</a> in the Camel user manual.
*
* @since 4.15
*/
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/EventFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/EventFactory.java
index 185af1b4b523..e38af2112bbc 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/EventFactory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/EventFactory.java
@@ -24,9 +24,25 @@ import org.apache.camel.Route;
import org.jspecify.annotations.Nullable;
/**
- * Factory to create {@link CamelEvent events} that are emitted when such an
event occur.
+ * Factory that mints concrete {@link CamelEvent} instances for every
significant lifecycle and messaging event in the
+ * Camel runtime.
* <p/>
- * For example when an {@link Exchange} is being created and then later when
its done.
+ * Camel defines a rich event taxonomy covering: {@link
org.apache.camel.CamelContext} lifecycle (initializing, started,
+ * stopped, suspended, resumed, reloaded), route lifecycle (starting, started,
stopping, stopped, added, removed,
+ * reloaded, restarting), service failures, and {@link Exchange} milestones
(created, completed, failed, redelivery,
+ * sending, sent, step start/complete/fail). Each method corresponds to one
event type and returns an instance populated
+ * with the relevant context information.
+ * <p/>
+ * The factory is set on {@link
ManagementStrategy#setEventFactory(EventFactory)} and called whenever
+ * {@link ManagementStrategy#notify(CamelEvent)} needs to fire a new event.
Timestamps can be included in events by
+ * setting {@link #setTimestampEnabled(boolean)} to {@code true}; they are
disabled by default to avoid overhead when
+ * not needed. A custom factory can extend the event set or change how event
objects are constructed.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/event-notifier.html";>Event
Notifier</a> in the Camel user manual.
+ *
+ * @see CamelEvent
+ * @see EventNotifier
+ * @see ManagementStrategy
*/
public interface EventFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/EventNotifier.java
b/core/camel-api/src/main/java/org/apache/camel/spi/EventNotifier.java
index b0bcd6f5068e..21edf65d9e65 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/EventNotifier.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/EventNotifier.java
@@ -17,10 +17,22 @@
package org.apache.camel.spi;
/**
- * Notifier to send {@link CamelEvent} notifications.
+ * Observer that receives {@link CamelEvent} notifications fired by the Camel
runtime.
+ * <p/>
+ * Notifiers are registered with {@link
ManagementStrategy#addEventNotifier(EventNotifier)} and receive every event that
+ * {@link ManagementStrategy#notify(CamelEvent)} dispatches. Common uses
include emitting metrics (Micrometer,
+ * Prometheus), publishing traces, audit logging, and driving test assertions.
+ * <p/>
+ * Each event category can be selectively suppressed via the {@code
setIgnore*} methods, which avoids the overhead of
+ * dispatching events that the notifier does not care about. For example, a
metrics-only notifier can ignore all route
+ * lifecycle events while still observing exchange sent/completed events. The
{@link EventFactory} is the counterpart
+ * that constructs the actual event objects.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/event-notifier.html";>Event
Notifier</a> in the Camel user manual.
*
* @see CamelEvent
* @see EventFactory
+ * @see ManagementStrategy
*/
public interface EventNotifier {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ExecutorServiceManager.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ExecutorServiceManager.java
index 4e3ae04c32d2..72de537e9fa4 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ExecutorServiceManager.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ExecutorServiceManager.java
@@ -49,8 +49,11 @@ import org.jspecify.annotations.Nullable;
* and {@link #shutdownNow(java.util.concurrent.ExecutorService)}, and {@link
#getShutdownAwaitTermination()} methods.
* Notice the details about using a graceful shutdown at first, and then
falling back to aggressive shutdown in case of
* await termination timeout occurred.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/threading-model.html";>Threading Model</a>
in the Camel user manual.
*
* @see ThreadPoolFactory
+ * @see ThreadPoolProfile
*/
public interface ExecutorServiceManager extends ShutdownableService,
StaticService {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementAgent.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementAgent.java
index 07196df0516c..783ae7bea1af 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementAgent.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementAgent.java
@@ -26,7 +26,24 @@ import org.apache.camel.Service;
import org.jspecify.annotations.Nullable;
/**
- * Camel JMX service agent
+ * Low-level JMX bridge that registers and unregisters Camel managed objects
in a {@link javax.management.MBeanServer}.
+ * <p/>
+ * {@link ManagementStrategy} is the high-level coordinator; it delegates all
MBean lifecycle operations (register,
+ * unregister, lookup) to this agent. The agent wraps an {@link
javax.management.MBeanServer} — by default the platform
+ * MBean server — and exposes a simplified API that hides the JMX plumbing
from the rest of Camel.
+ * <p/>
+ * The agent is created by {@link ManagementStrategyFactory} and is available
from a running
+ * {@link org.apache.camel.CamelContext} via {@link
ManagementStrategy#getManagementAgent()}. Its configuration
+ * properties (domain name, statistics level, MBeans level, naming pattern,
masking, etc.) map directly to the
+ * {@code camel.main.jmx-*} family of properties. The {@link
ManagementObjectNameStrategy} and
+ * {@link ManagementObjectStrategy} work alongside the agent to determine the
{@link javax.management.ObjectName} and
+ * managed-object wrapper for each Camel artifact before the agent registers
it.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/jmx.html";>JMX</a> in the Camel
user manual.
+ *
+ * @see ManagementStrategy
+ * @see ManagementObjectNameStrategy
+ * @see ManagementObjectStrategy
*/
public interface ManagementAgent extends Service {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementInterceptStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementInterceptStrategy.java
index a0f96c5e751f..345414380690 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementInterceptStrategy.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementInterceptStrategy.java
@@ -24,7 +24,24 @@ import org.apache.camel.Processor;
import org.jspecify.annotations.Nullable;
/**
- * A specialized {@link InterceptStrategy} which is used for JMX management
for EIPs.
+ * SPI that wraps EIP {@link org.apache.camel.Processor}s with instrumentation
so that per-exchange statistics can be
+ * collected and exposed via JMX MBeans.
+ * <p/>
+ * At route startup, the JMX management lifecycle strategy calls
+ * {@link #createProcessor(org.apache.camel.NamedNode,
org.apache.camel.Processor)} for each processor defined in a
+ * route. The returned {@link InstrumentationProcessor} delegates to the real
processor while invoking
+ * {@link InstrumentationProcessor#before} and {@link
InstrumentationProcessor#after} around each exchange to record
+ * timing, exchange counts, and error counts. Those counters are then surfaced
through the corresponding managed MBean
+ * (for example, a processor MBean registered by {@link
ManagementObjectStrategy}).
+ * <p/>
+ * The inner {@link InstrumentationProcessor} interface extends {@link
org.apache.camel.AsyncProcessor} and
+ * {@link org.apache.camel.Ordered} so that multiple interceptors can be
stacked in a defined order without blocking the
+ * async dispatch path.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/jmx.html";>JMX</a> in the Camel
user manual.
+ *
+ * @see ManagementStrategy
+ * @see ManagementObjectStrategy
*/
public interface ManagementInterceptStrategy {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementMBeanAssembler.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementMBeanAssembler.java
index 7584e8464fac..5ef89c1750d7 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementMBeanAssembler.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementMBeanAssembler.java
@@ -25,8 +25,24 @@ import org.apache.camel.StaticService;
import org.jspecify.annotations.Nullable;
/**
- * An assembler to assemble a {@link
javax.management.modelmbean.RequiredModelMBean} which can be used to register
the
- * object in JMX.
+ * Assembles a {@link javax.management.modelmbean.ModelMBean} from a Camel
managed object so it can be registered in the
+ * {@link javax.management.MBeanServer}.
+ * <p/>
+ * Camel's JMX layer does not require managed objects to implement a fixed
MBean interface. Instead, managed facades
+ * (such as {@code ManagedCamelContext} or {@code ManagedRoute}) are annotated
with
+ * {@code @org.apache.camel.api.management.ManagedResource}, {@code
@ManagedAttribute}, and {@code @ManagedOperation}.
+ * The assembler scans those annotations and builds a {@link
javax.management.modelmbean.RequiredModelMBean} that
+ * exposes exactly the declared attributes and operations.
+ * <p/>
+ * The {@link ManagementAgent} calls
+ * {@link #assemble(javax.management.MBeanServer, Object,
javax.management.ObjectName)} for each managed object before
+ * registering it. Replacing this implementation allows custom annotation
processors or alternative MBean descriptors to
+ * be used.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/jmx.html";>JMX</a> in the Camel
user manual.
+ *
+ * @see ManagementAgent
+ * @see ManagementObjectStrategy
*/
public interface ManagementMBeanAssembler extends StaticService {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementNameStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementNameStrategy.java
index b0b6207d413c..a11b9b1df227 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementNameStrategy.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementNameStrategy.java
@@ -19,22 +19,29 @@ package org.apache.camel.spi;
import org.jspecify.annotations.Nullable;
/**
- * Strategy for assigning the name part of the {@link
javax.management.ObjectName} for a managed
+ * Strategy for assigning the {@code name} segment of the {@link
javax.management.ObjectName} for a managed
* {@link org.apache.camel.CamelContext}.
* <p/>
- * A strategy is needed as you can run multiple CamelContext in the same JVM,
and want them to be enlisted in the JVM
- * wide JMXMBeanServer. And this requires a strategy to be able to calculate
unique names, in case of clashes. Or to
- * enforce an explicit fixed name, to ensure the JMX name is not using dynamic
counters etc.
+ * A strategy is needed because multiple {@link org.apache.camel.CamelContext}
instances can run in the same JVM and
+ * share the same JMX {@link javax.management.MBeanServer}. The strategy
either computes a unique name automatically
+ * (using an incrementing counter or the context name) or enforces a fixed
name so the JMX key remains stable across
+ * restarts.
* <p/>
- * This strategy supports a naming pattern which supports at least the
following tokens
+ * The naming pattern supports at least the following tokens:
* <ul>
- * <li>#camelId# - the camel id (eg the camel name)</li>
- * <li>#name# - same as #camelId#</li>
- * <li>#counter# - an incrementing counter</li>
+ * <li>{@code #camelId#} - the Camel context id (its configured name)</li>
+ * <li>{@code #name#} - same as {@code #camelId#}</li>
+ * <li>{@code #counter#} - an incrementing counter that guarantees
uniqueness</li>
* </ul>
+ * <p/>
+ * This strategy controls only the {@code name=} key within the domain; the
full {@link javax.management.ObjectName}
+ * construction (including all other key-value pairs) is the responsibility of
{@link ManagementObjectNameStrategy}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/jmx.html";>JMX</a> in the Camel
user manual.
*
* @see CamelContextNameStrategy
- * @see org.apache.camel.impl.DefaultManagementNameStrategy
+ * @see ManagementObjectNameStrategy
+ * @see ManagementAgent
*/
public interface ManagementNameStrategy {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementObjectNameStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementObjectNameStrategy.java
index a8ae8a6cf75d..f19cab4c6948 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementObjectNameStrategy.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementObjectNameStrategy.java
@@ -35,7 +35,23 @@ import org.apache.camel.cluster.CamelClusterService;
import org.jspecify.annotations.Nullable;
/**
- * Strategy for computing {@link ObjectName} names for the various beans that
Camel register for management.
+ * Strategy for computing the full {@link ObjectName} (domain plus all
key-value properties) for every Camel artifact
+ * registered in JMX.
+ * <p/>
+ * A JMX {@link ObjectName} encodes both a domain (e.g., {@code
org.apache.camel}) and a set of typed key-value pairs
+ * (e.g., {@code context=myApp, type=routes, name=myRoute}). This strategy
provides a dedicated factory method for each
+ * Camel artifact type so that the correct type key and identifying attributes
are always applied consistently.
+ * <p/>
+ * The {@link ManagementStrategy} calls the appropriate {@code
getObjectNameFor*} method before invoking
+ * {@link ManagementAgent#register(Object, ObjectName)} or {@link
ManagementAgent#unregister(ObjectName)}. The domain
+ * portion of the {@link ObjectName} is configured on {@link
ManagementAgent#getMBeanObjectDomainName()}, while the name
+ * key within the context entry is governed by {@link ManagementNameStrategy}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/jmx.html";>JMX</a> in the Camel
user manual.
+ *
+ * @see ManagementNameStrategy
+ * @see ManagementObjectStrategy
+ * @see ManagementAgent
*/
public interface ManagementObjectNameStrategy {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementObjectStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementObjectStrategy.java
index 26e1792958b3..bb48ad53562e 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementObjectStrategy.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementObjectStrategy.java
@@ -33,7 +33,23 @@ import org.apache.camel.health.HealthCheckRegistry;
import org.jspecify.annotations.Nullable;
/**
- * Strategy for creating the managed object for the various beans Camel
register for management.
+ * Strategy that creates the managed wrapper objects Camel registers in JMX
for its internal artifacts.
+ * <p/>
+ * Before Camel can register a {@link org.apache.camel.CamelContext}, {@link
org.apache.camel.Route},
+ * {@link org.apache.camel.Processor}, {@link org.apache.camel.Component}, or
other runtime object as an MBean, it needs
+ * a managed facade that exposes the right attributes and operations. This
strategy supplies those facades (for example,
+ * {@code ManagedCamelContext}, {@code ManagedRoute}, {@code
ManagedProcessor}) for each artifact type.
+ * <p/>
+ * The {@link ManagementStrategy} calls the appropriate {@code
getManagedObjectFor*} method, then the returned object is
+ * assembled into a {@link javax.management.modelmbean.ModelMBean} by {@link
ManagementMBeanAssembler} and registered
+ * under the {@link javax.management.ObjectName} computed by {@link
ManagementObjectNameStrategy}. Replacing this
+ * strategy allows advanced users to substitute custom MBean facades for any
Camel type.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/jmx.html";>JMX</a> in the Camel
user manual.
+ *
+ * @see ManagementObjectNameStrategy
+ * @see ManagementMBeanAssembler
+ * @see ManagementStrategy
*/
public interface ManagementObjectStrategy {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementStrategy.java
index 4920afa631a7..fa28138ea634 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementStrategy.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementStrategy.java
@@ -23,15 +23,25 @@ import org.apache.camel.Service;
import org.apache.camel.StaticService;
/**
- * Strategy for management.
+ * Top-level SPI for Camel's management and observability layer, coordinating
JMX registration, lifecycle events, and
+ * statistics collection across all Camel artifacts.
* <p/>
- * If JMX is detected (camel-management JAR on the classpath) then
org.apache.camel.management.JmxManagementStrategy is
- * in use. Otherwise, the DefaultManagementStrategy is in use.
+ * When the {@code camel-management} JAR is on the classpath, {@code
JmxManagementStrategy} is activated and delegates
+ * MBean registration to a {@link ManagementAgent}. Without that JAR, {@code
DefaultManagementStrategy} is used, which
+ * still dispatches lifecycle events to registered {@link EventNotifier}s but
does not expose JMX MBeans.
* <p/>
- * You can also plugin and use a 3rd party management implementation with
Camel.
+ * The strategy is the central hub for two concerns: management objects
(registering and unregistering Camel components,
+ * routes, processors, etc. as MBeans via {@link ManagementObjectStrategy} and
{@link ManagementObjectNameStrategy}) and
+ * events (delivering {@link CamelEvent} notifications to all registered
{@link EventNotifier}s via
+ * {@link #notify(CamelEvent)}). A third-party management backend can be
plugged in by implementing this interface and
+ * providing a {@link ManagementStrategyFactory}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/jmx.html";>JMX</a> in the Camel
user manual.
*
- * @see org.apache.camel.spi.EventNotifier
- * @see org.apache.camel.spi.EventFactory
+ * @see ManagementAgent
+ * @see EventNotifier
+ * @see EventFactory
+ * @see ManagementStrategyFactory
*/
public interface ManagementStrategy extends StaticService {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementStrategyFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementStrategyFactory.java
index 7666c72b07ca..17f7a2c3d22e 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ManagementStrategyFactory.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ManagementStrategyFactory.java
@@ -22,7 +22,21 @@ import org.apache.camel.CamelContext;
import org.jspecify.annotations.Nullable;
/**
- * Service Factory for ManagementStrategy
+ * SPI factory that creates the {@link ManagementStrategy} and its associated
{@link LifecycleStrategy} for a
+ * {@link org.apache.camel.CamelContext}.
+ * <p/>
+ * Camel discovers implementations via {@link FactoryFinder} from the {@code
META-INF/services/} directory. Adding
+ * {@code camel-management} to the classpath registers the JMX-backed factory;
without it the default no-op strategy is
+ * used. The factory produces three artifacts: a {@link ManagementStrategy}
(which owns the event-notifier list and
+ * delegates to the {@link ManagementAgent}), an optional {@link
LifecycleStrategy} (which listens to route and service
+ * lifecycle events and drives MBean registration), and then wires both into
the context via
+ * {@link #setupManagement(org.apache.camel.CamelContext, ManagementStrategy,
LifecycleStrategy)}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/jmx.html";>JMX</a> in the Camel
user manual.
+ *
+ * @see ManagementStrategy
+ * @see ManagementAgent
+ * @see FactoryFinder
*/
public interface ManagementStrategyFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ReactiveExecutor.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ReactiveExecutor.java
index 1c26fa25fdd9..f44f16b7fabc 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ReactiveExecutor.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ReactiveExecutor.java
@@ -17,8 +17,22 @@
package org.apache.camel.spi;
/**
- * SPI to plugin different reactive engines in the Camel routing engine.
+ * SPI for plugging a custom reactive (non-blocking) dispatch engine into
Camel's internal routing loop.
+ * <p/>
+ * Camel's async routing engine decomposes message processing into a series of
continuation tasks rather than blocking a
+ * thread for the full duration of a route. This interface is the hook point
that decides how those continuations are
+ * queued and executed: {@link #schedule(Runnable)} for fair background
dispatch, {@link #scheduleMain(Runnable)} for
+ * high-priority dispatch that should run as soon as possible, {@link
#scheduleSync(Runnable)} to run on the current
+ * thread immediately, and {@link #scheduleQueue(Runnable)} to defer to the
current-thread queue (used for transactional
+ * routing where all steps must run on the same thread).
+ * <p/>
+ * The built-in {@code DefaultReactiveExecutor} uses a simple single-threaded
loop driven by the calling thread.
+ * Alternative implementations can delegate to Vert.x, Project Reactor, or
other reactive runtimes. The factory key
+ * {@link #FACTORY} is used by {@link FactoryFinder} for discovery.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/threading-model.html";>Threading Model</a>
in the Camel user manual.
*
+ * @see ExecutorServiceManager
* @since 3.0
*/
public interface ReactiveExecutor {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ScheduledPollConsumerScheduler.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ScheduledPollConsumerScheduler.java
index 5fc6607f2420..f96e20b43187 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ScheduledPollConsumerScheduler.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ScheduledPollConsumerScheduler.java
@@ -21,13 +21,21 @@ import org.apache.camel.Consumer;
import org.apache.camel.ShutdownableService;
/**
- * A pluggable scheduler for {@link
org.apache.camel.support.ScheduledPollConsumer} consumers.
+ * Pluggable scheduler that controls when a {@link
org.apache.camel.support.ScheduledPollConsumer} wakes up to poll its
+ * source.
* <p/>
- * The default implementation {@link
org.apache.camel.support.DefaultScheduledPollConsumerScheduler} is using the
- * {@link java.util.concurrent.ScheduledExecutorService} from the JDK to
schedule and run the poll task.
+ * Polling consumers (file, FTP, mail, etc.) delegate all scheduling decisions
to this SPI so that the polling trigger
+ * can be replaced without changing the consumer itself. The default
implementation uses a
+ * {@link java.util.concurrent.ScheduledExecutorService} with a fixed or
initial delay, while the {@code camel-quartz}
+ * component provides an alternative that accepts CRON expressions for
time-based firing.
* <p/>
- * An alternative implementation is in <tt>camel-quartz</tt> component that
allows to use CRON expression to define when
- * the scheduler should run.
+ * A scheduler is initialized via {@link #onInit(org.apache.camel.Consumer)}
and then activated by calling
+ * {@link #startScheduler()}, which begins firing the task registered with
{@link #scheduleTask(Runnable)}. The consumer
+ * task itself is responsible for calling the consumer's polling logic; the
scheduler only controls the firing cadence.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/polling-consumer.html";>Polling
Consumer</a> in the Camel user manual.
+ *
+ * @see ExecutorServiceManager
*/
public interface ScheduledPollConsumerScheduler extends ShutdownableService,
CamelContextAware {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ThreadPoolFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ThreadPoolFactory.java
index 5336e984b103..970920494667 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ThreadPoolFactory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ThreadPoolFactory.java
@@ -21,11 +21,23 @@ import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.ThreadFactory;
/**
- * Creates ExecutorService and ScheduledExecutorService objects that work with
a thread pool for a given
- * ThreadPoolProfile and ThreadFactory.
+ * Low-level SPI for constructing {@link java.util.concurrent.ExecutorService}
and
+ * {@link java.util.concurrent.ScheduledExecutorService} instances from a
{@link ThreadPoolProfile} and a
+ * {@link java.util.concurrent.ThreadFactory}.
+ * <p/>
+ * This interface uses only standard JDK types, which makes it the right
customization point for environments (such as
+ * JEE application servers) where thread pool creation must be delegated to a
managed thread pool or WorkManager rather
+ * than created directly via {@link java.util.concurrent.Executors}. The
higher-level {@link ExecutorServiceManager}
+ * handles Camel-specific concerns such as profile lookup, thread naming,
lifecycle tracking, and graceful shutdown;
+ * this factory simply creates the pool when asked.
+ * <p/>
+ * The factory is discovered via {@link FactoryFinder} using the key {@link
#FACTORY}. Camel ships
+ * {@code DefaultThreadPoolFactory} as the built-in implementation.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/threading-model.html";>Threading Model</a>
in the Camel user manual.
*
- * This interface allows customizing the creation of these objects to adapt
camel for application servers and other
- * environments where thread pools should not be created with the jdk methods
+ * @see ExecutorServiceManager
+ * @see ThreadPoolProfile
*/
public interface ThreadPoolFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ThreadPoolProfile.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ThreadPoolProfile.java
index c4fab2f09c15..a5038c0d5b2c 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ThreadPoolProfile.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ThreadPoolProfile.java
@@ -26,9 +26,22 @@ import
org.apache.camel.util.concurrent.ThreadPoolRejectedPolicy;
import org.jspecify.annotations.Nullable;
/**
- * A profile which defines thread pool settings.
+ * A named, reusable configuration template for {@link
java.util.concurrent.ThreadPoolExecutor} settings managed by the
+ * {@link ExecutorServiceManager}.
* <p/>
- * See more details at <a
href="https://camel.apache.org/threading-model.html";>threading model</a>
+ * Rather than hard-coding pool parameters at each call site, Camel components
and EIPs declare a profile id (or use the
+ * default profile). The {@link ExecutorServiceManager} looks up the profile
and passes it to the
+ * {@link ThreadPoolFactory} to create the actual pool. The default profile
provides baseline values (typically
+ * {@code poolSize=10, maxPoolSize=20, keepAlive=60s, maxQueueSize=1000}) that
are applied whenever a parameter is not
+ * explicitly set on a custom profile.
+ * <p/>
+ * A profile is also the vehicle for configuring the rejected-execution policy
via {@link #setRejectedPolicy}, which
+ * determines what happens when the work queue is full and all threads are
busy.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/threading-model.html";>Threading Model</a>
in the Camel user manual.
+ *
+ * @see ExecutorServiceManager
+ * @see ThreadPoolFactory
*/
public class ThreadPoolProfile implements Serializable, Cloneable {
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/Tracer.java
b/core/camel-api/src/main/java/org/apache/camel/spi/Tracer.java
index 83eb390776c2..a7786de292f3 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/Tracer.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/Tracer.java
@@ -24,8 +24,24 @@ import org.apache.camel.StaticService;
import org.jspecify.annotations.Nullable;
/**
- * SPI for tracing messages.
+ * SPI for intercepting {@link org.apache.camel.Exchange} flow at each EIP
node in a route for tracing and debugging
+ * purposes.
+ * <p/>
+ * The tracer hooks into the routing pipeline at every {@link
org.apache.camel.NamedNode} EIP and fires
+ * {@link #traceBeforeNode}/{@link #traceAfterNode} around each step, plus
+ * {@link #traceBeforeRoute}/{@link #traceAfterRoute} for the route entry and
exit. Two built-in implementations exist:
+ * {@link BacklogTracer} (buffered in-memory capture accessible via JMX or the
developer console) and the OpenTelemetry
+ * tracer in {@code camel-opentelemetry} (exports spans to distributed tracing
backends).
+ * <p/>
+ * Tracers support a standby mode: when {@link #isStandby()} is {@code true}
the tracer is wired into the pipeline at
+ * startup but does not record anything until manually enabled, which avoids
restart overhead when toggling tracing via
+ * JMX at runtime. The {@link #setTracePattern(String)} and {@link
#setTraceTemplates(boolean)} options limit which
+ * nodes are traced to reduce verbosity.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/tracer.html";>Tracer</a> in the
Camel user manual.
*
+ * @see BacklogTracer
+ * @see ManagementStrategy
* @since 3.0
*/
public interface Tracer extends StaticService {
