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 deedbe3dc952 CAMEL-23535: camel-api - batches 8-9: enhance Javadoc for
registry, DI, and route lifecycle SPIs
deedbe3dc952 is described below
commit deedbe3dc952a03c9f5727231c0b68c3363c00fe
Author: Adriano Machado <[email protected]>
AuthorDate: Mon Jun 8 01:16:58 2026 -0400
CAMEL-23535: camel-api - batches 8-9: enhance Javadoc for registry, DI, and
route lifecycle SPIs
Enhance class-level Javadoc for 19 interfaces across two subsystems in
core/camel-api: registry and dependency injection SPIs (BeanRepository,
BeanIntrospection, BeanProcessorFactory, BeanProxyFactory,
ComponentResolver,
ComponentNameResolver, Configurer, ConfigurerResolver, ConfigurerStrategy)
and route lifecycle SPIs (RouteController, SupervisingRouteController,
RoutePolicy, RoutePolicyFactory, ShutdownStrategy, ShutdownRoute,
ShutdownRunningTask, StartupCondition, StartupStepRecorder,
RouteStartupOrder). Javadoc-only changes with minor grammar fixes.
Closes #23823
---
.../main/java/org/apache/camel/ShutdownRoute.java | 18 +++++------
.../java/org/apache/camel/ShutdownRunningTask.java | 19 ++++++------
.../org/apache/camel/spi/BeanIntrospection.java | 18 ++++++++---
.../org/apache/camel/spi/BeanProcessorFactory.java | 17 +++++++---
.../org/apache/camel/spi/BeanProxyFactory.java | 13 ++++++--
.../java/org/apache/camel/spi/BeanRepository.java | 15 +++++++--
.../apache/camel/spi/ComponentNameResolver.java | 8 ++++-
.../org/apache/camel/spi/ComponentResolver.java | 14 ++++++++-
.../main/java/org/apache/camel/spi/Configurer.java | 18 +++++++++--
.../org/apache/camel/spi/ConfigurerResolver.java | 11 ++++++-
.../org/apache/camel/spi/ConfigurerStrategy.java | 11 ++++++-
.../java/org/apache/camel/spi/RouteController.java | 17 +++++++++-
.../java/org/apache/camel/spi/RoutePolicy.java | 17 ++++++----
.../org/apache/camel/spi/RoutePolicyFactory.java | 15 +++++++--
.../org/apache/camel/spi/RouteStartupOrder.java | 14 +++++++--
.../org/apache/camel/spi/ShutdownStrategy.java | 36 ++++++++++++----------
.../org/apache/camel/spi/StartupCondition.java | 13 +++++---
.../org/apache/camel/spi/StartupStepRecorder.java | 16 ++++++++--
.../camel/spi/SupervisingRouteController.java | 19 +++++++++---
19 files changed, 232 insertions(+), 77 deletions(-)
diff --git a/core/camel-api/src/main/java/org/apache/camel/ShutdownRoute.java
b/core/camel-api/src/main/java/org/apache/camel/ShutdownRoute.java
index f91099fe3149..738cbcec8997 100644
--- a/core/camel-api/src/main/java/org/apache/camel/ShutdownRoute.java
+++ b/core/camel-api/src/main/java/org/apache/camel/ShutdownRoute.java
@@ -20,20 +20,20 @@ import jakarta.xml.bind.annotation.XmlEnum;
import jakarta.xml.bind.annotation.XmlType;
/**
- * Represents the options available when shutting down routes.
+ * Per-route policy controlling whether the route stops immediately or defers
during
+ * <a href="https://camel.apache.org/manual/graceful-shutdown.html";>graceful
shutdown</a>.
* <p/>
- * Is used for example to defer shutting down a route until all inflight
exchanges have been completed, after which the
- * route can be shutdown safely.
- * <p/>
- * This allows fine grained configuration in accomplishing graceful shutdown
where you have for example some internal
- * route which other routes are dependent upon.
+ * Set on a route via the DSL {@code .shutdownRoute(ShutdownRoute.Defer)}
call. Deferring is useful for shared internal
+ * routes (for example a {@code direct:} or {@code seda:} route used by many
other routes) that must remain active until
+ * all dependent routes have stopped processing their in-flight exchanges. The
+ * {@link org.apache.camel.spi.ShutdownStrategy} honours the deferred routes
by stopping them last.
* <ul>
- * <li>Default - The <b>default</b> behavior where a route will attempt to
shutdown now</li>
- * <li>Defer - Will defer shutting down the route and let it be active during
graceful shutdown. The route will be
- * shutdown at a later stage during the graceful shutdown process.</li>
+ * <li>{@link #Default} - attempt to stop the route as soon as the shutdown
sequence reaches it.</li>
+ * <li>{@link #Defer} - keep the route running and stop it only after all
{@code Default} routes have stopped.</li>
* </ul>
*
* @see ShutdownRunningTask
+ * @see org.apache.camel.spi.ShutdownStrategy
*/
@XmlType
@XmlEnum
diff --git
a/core/camel-api/src/main/java/org/apache/camel/ShutdownRunningTask.java
b/core/camel-api/src/main/java/org/apache/camel/ShutdownRunningTask.java
index fd2e6f141ab6..9988262e53c7 100644
--- a/core/camel-api/src/main/java/org/apache/camel/ShutdownRunningTask.java
+++ b/core/camel-api/src/main/java/org/apache/camel/ShutdownRunningTask.java
@@ -20,21 +20,22 @@ import jakarta.xml.bind.annotation.XmlEnum;
import jakarta.xml.bind.annotation.XmlType;
/**
- * Represents the kind of options for what to do with the current task when
shutting down.
+ * Per-consumer policy controlling how many pending tasks are processed before
the consumer stops during
+ * <a href="https://camel.apache.org/manual/graceful-shutdown.html";>graceful
shutdown</a>.
* <p/>
- * By default the current task is allowed to complete. However some consumers
such as {@link BatchConsumer} have pending
- * tasks which you can configure the consumer to complete as well.
+ * Set on a route via the DSL {@code
.shutdownRunningTask(ShutdownRunningTask.CompleteAllTasks)} call. Most consumers
+ * handle a single task at a time, so the distinction only matters for {@link
BatchConsumer} implementations (such as
+ * file or JPA consumers) that can have multiple pending messages in a batch
when shutdown is triggered.
* <ul>
- * <li>CompleteCurrentTaskOnly - Is the <b>default</b> behavior where a route
consumer will be shutdown as fast as
- * possible. Allowing it to complete its current task, but not to pickup
pending tasks (if any).</li>
- * <li>CompleteAllTasks - Allows a route consumer to continue to complete all
pending tasks (if any).</li>
- *
+ * <li>{@link #CompleteCurrentTaskOnly} - the <b>default</b>: finish the
current in-flight task and then stop; any
+ * remaining pending tasks are left unprocessed.</li>
+ * <li>{@link #CompleteAllTasks} - drain the entire current batch before
stopping; only applicable to
+ * {@link BatchConsumer} consumers.</li>
* </ul>
- * <b>Notice:</b> Most consumers only have a single task, but {@link
org.apache.camel.BatchConsumer} can have many tasks
- * and thus this option mostly applies to this kind of consumer.
*
* @see ShutdownRoute
* @see BatchConsumer
+ * @see org.apache.camel.spi.ShutdownStrategy
*/
@XmlType
@XmlEnum
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/BeanIntrospection.java
b/core/camel-api/src/main/java/org/apache/camel/spi/BeanIntrospection.java
index 6d547895c74f..213864d6b73f 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/BeanIntrospection.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/BeanIntrospection.java
@@ -28,11 +28,21 @@ import org.apache.camel.TypeConverter;
import org.jspecify.annotations.Nullable;
/**
- * Used for introspecting beans properties via Java reflection; such as
extracting current property values, or updating
- * one or more properties etc.
- *
- * End users should favour using {@link
org.apache.camel.support.PropertyBindingSupport} instead.
+ * Low-level SPI for reading and writing bean properties via Java reflection,
used internally by Camel's property
+ * binding infrastructure.
+ * <p/>
+ * This interface operates directly on getter/setter pairs discovered at
runtime and is consulted by Camel when
+ * configuring components, endpoints, and EIP options from properties files,
YAML, or the
+ * <a href="https://camel.apache.org/manual/camel-jbang.html";>Camel JBang</a>
CLI. Introspection results are cached
+ * internally to minimise repeated reflection calls during
configuration-intensive startup sequences. Call
+ * {@link #clearCache()} to invalidate the cache when class definitions change
at runtime (for example in OSGi
+ * hot-deployment scenarios).
+ * <p/>
+ * End users should prefer the higher-level {@link
org.apache.camel.support.PropertyBindingSupport} utility, which
+ * handles placeholder resolution, type conversion, and nested property paths
on top of this interface.
*
+ * @see org.apache.camel.support.PropertyBindingSupport
+ * @see PropertyConfigurer
* @since 3.0
*/
public interface BeanIntrospection extends StaticService,
AfterPropertiesConfigured {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/BeanProcessorFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/BeanProcessorFactory.java
index 6fdb4036f135..d50f999a1b47 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/BeanProcessorFactory.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/BeanProcessorFactory.java
@@ -24,11 +24,20 @@ import org.apache.camel.Processor;
import org.jspecify.annotations.Nullable;
/**
- * Factory for creating a {@link Processor} that can invoke a method on a bean
and supporting using Camel bean parameter
- * bindings.
+ * Factory for creating a {@link Processor} that invokes a method on a bean
with full support for
+ * <a href="https://camel.apache.org/manual/bean-integration.html";>Camel bean
parameter bindings</a>.
* <p/>
- * This requires to have camel-bean on the classpath.
+ * When a route contains a {@code .bean()} DSL call, Camel delegates processor
creation to this factory. The factory
+ * implementation lives in {@code camel-bean} (loaded via the META-INF service
file convention) and supports resolving
+ * the target bean from multiple sources: a direct instance, a registry
reference by name, a class name, or a
+ * {@link Class} literal. The {@code method} parameter may be omitted to let
Camel auto-select the best matching method
+ * using the bean-binding algorithm.
+ * <p/>
+ * The {@code scope} parameter controls bean lifecycle: {@link
org.apache.camel.BeanScope#Singleton} reuses one shared
+ * instance, while {@link org.apache.camel.BeanScope#Prototype} creates a new
instance per exchange.
*
+ * @see BeanProxyFactory
+ * @see BeanRepository
* @since 3.0
*/
public interface BeanProcessorFactory {
@@ -57,7 +66,7 @@ public interface BeanProcessorFactory {
* @param bean the bean instance
* @param beanType or the bean class name
* @param beanClass or the bean class
- * @param ref or bean reference to lookup the bean from the
registry
+ * @param ref or bean reference to look up the bean from the
registry
* @param method optional name of method to invoke
* @param scope the scope of the bean
* @return the created processor
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/BeanProxyFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/BeanProxyFactory.java
index 0485b2a2108a..8f4f2ac8cf5c 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/BeanProxyFactory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/BeanProxyFactory.java
@@ -19,10 +19,19 @@ package org.apache.camel.spi;
import org.apache.camel.Endpoint;
/**
- * A factory for creating a {@link java.lang.reflect.Proxy} for a bean.
+ * Factory for creating a {@link java.lang.reflect.Proxy} facade that routes
method invocations to a Camel
+ * {@link org.apache.camel.Endpoint} as messages.
* <p/>
- * This requires to have camel-bean on the classpath.
+ * The generated proxy implements one or more caller-supplied interfaces. Each
method call on the proxy is translated
+ * into a Camel {@link org.apache.camel.Exchange} and sent to the configured
endpoint, making it straightforward to
+ * invoke Camel routes from plain Java code without depending on Camel APIs at
the call site. This capability is part of
+ * the <a href="https://camel.apache.org/manual/bean-integration.html";>bean
integration</a> feature and requires
+ * {@code camel-bean} on the classpath; the implementation is loaded via the
META-INF service key {@link #FACTORY}.
+ * <p/>
+ * When {@code binding} is {@code true}, multi-parameter methods are mapped
using the standard Camel bean-parameter
+ * binding algorithm (matching by type, annotation, or position).
*
+ * @see BeanProcessorFactory
* @since 3.0
*/
public interface BeanProxyFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/BeanRepository.java
b/core/camel-api/src/main/java/org/apache/camel/spi/BeanRepository.java
index bff4586e6353..d7d750ffe495 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/BeanRepository.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/BeanRepository.java
@@ -23,9 +23,20 @@ import org.apache.camel.NoSuchBeanTypeException;
import org.jspecify.annotations.Nullable;
/**
- * Represents a bean repository used to lookup components by name and type.
This allows Camel to plugin to third-party
- * bean repositories such as Spring, JNDI, OSGi.
+ * Pluggable contract for looking up beans by name or type, forming the
foundation of Camel's
+ * <a href="https://camel.apache.org/manual/registry.html";>Registry</a>.
+ * <p/>
+ * At runtime, the active {@link org.apache.camel.CamelContext} exposes a
composite
+ * {@link org.apache.camel.spi.Registry} that delegates to one or more {@code
BeanRepository} instances, allowing Camel
+ * to integrate with external containers such as Spring {@code
ApplicationContext}, CDI, JNDI, or OSGi service
+ * registries without changes to core code. The composited view is used
transparently whenever a route references a bean
+ * by name (for example in the {@code .bean()} DSL call) or when Camel
auto-wires component options from the registry.
+ * <p/>
+ * Lookup is available in three forms: by name only ({@link #lookupByName}),
by name and expected type
+ * ({@link #lookupByNameAndType}), and by type alone ({@link #findByType} /
{@link #findByTypeWithName}). Prefer the
+ * typed variants to avoid ambiguity when the same name is bound more than
once.
*
+ * @see org.apache.camel.spi.Registry
* @since 3.0
*/
public interface BeanRepository {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ComponentNameResolver.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ComponentNameResolver.java
index 0f0663e6a56b..7b6fcdae4d8e 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ComponentNameResolver.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ComponentNameResolver.java
@@ -21,8 +21,14 @@ import java.util.Set;
import org.apache.camel.CamelContext;
/**
- * Discovers which components are available on the classpath.
+ * Discovers the names of all {@link org.apache.camel.Component}
implementations available on the classpath at runtime.
+ * <p/>
+ * The default implementation reads {@code
META-INF/services/org/apache/camel/component/} resource entries to enumerate
+ * registered component names without instantiating them. This list is used by
Camel tooling features such as
+ * auto-completion in the <a
href="https://camel.apache.org/manual/camel-jbang.html";>Camel JBang</a> CLI and
the catalog
+ * to answer questions like "which components are installed?" without
triggering lazy component loading.
*
+ * @see ComponentResolver
* @since 3.2
*/
public interface ComponentNameResolver {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ComponentResolver.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ComponentResolver.java
index 3847bf8a02e2..f48a9f0b99f0 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ComponentResolver.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ComponentResolver.java
@@ -21,7 +21,19 @@ import org.apache.camel.Component;
import org.jspecify.annotations.Nullable;
/**
- * Represents a resolver of components from a URI to be able to autoload them
using some discovery mechanism.
+ * Pluggable strategy for autoloading a {@link org.apache.camel.Component}
instance from a URI scheme the first time
+ * that scheme is encountered by a {@link org.apache.camel.CamelContext}.
+ * <p/>
+ * When a route references an endpoint URI whose scheme is not yet registered
in the context, Camel queries the active
+ * {@code ComponentResolver} with the scheme name. The default implementation
reads the service class name from
+ * {@code META-INF/services/org/apache/camel/component/<name>} on the
classpath, instantiates it, and adds it to the
+ * context. Alternative resolvers (for example Spring, OSGi, or custom
container integrations) may satisfy the lookup
+ * from their own registries instead.
+ * <p/>
+ * Component discovery is lazy: only components that are actually referenced
in routes are loaded.
+ *
+ * @see ComponentNameResolver
+ * @see org.apache.camel.Component
*/
public interface ComponentResolver {
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/Configurer.java
b/core/camel-api/src/main/java/org/apache/camel/spi/Configurer.java
index 536648996467..28e46562a10f 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/Configurer.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/Configurer.java
@@ -23,9 +23,23 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * An annotation used to mark classes to indicate code capable of configuring
its options via a getter/setters that can
- * be called via Camels {@link org.apache.camel.spi.PropertyConfigurer}.
+ * Marks a class as a candidate for build-time code generation of a {@link
PropertyConfigurer} implementation by the
+ * {@code camel-package-maven-plugin}.
+ * <p/>
+ * At build time, the Camel Maven plugin scans for types annotated with {@code
@Configurer} and generates a companion
+ * {@code *Configurer} class that sets properties directly via setters,
avoiding reflection at runtime. The generated
+ * class implements {@link PropertyConfigurer} and is registered in
+ * {@code META-INF/services/org/apache/camel/configurer/} so that {@link
ConfigurerResolver} can locate it by name. This
+ * pattern is used pervasively for {@link org.apache.camel.Component}, {@link
org.apache.camel.Endpoint}, and EIP model
+ * classes to keep configuration-path performance constant regardless of the
number of properties.
+ * <p/>
+ * Set {@link #bootstrap()} to {@code true} for types that are configured only
during startup; the generated configurer
+ * is then eligible for memory reclamation via {@link
ConfigurerStrategy#clearBootstrapConfigurers()} after the context
+ * has started.
*
+ * @see PropertyConfigurer
+ * @see ConfigurerResolver
+ * @see ConfigurerStrategy
* @since 3.3
*/
@Retention(RetentionPolicy.RUNTIME)
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ConfigurerResolver.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ConfigurerResolver.java
index d429858e6ea2..bcbbde2b04cc 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ConfigurerResolver.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ConfigurerResolver.java
@@ -20,8 +20,17 @@ import org.apache.camel.CamelContext;
import org.jspecify.annotations.Nullable;
/**
- * A pluggable strategy for resolving different configurers in a loosely
coupled manner
+ * Pluggable strategy for resolving a {@link PropertyConfigurer} by the name
of the target type (for example
+ * {@code timer-component} or {@code timer-endpoint}).
+ * <p/>
+ * The default implementation looks up the class name from a service resource
under the path
+ * {@link #RESOURCE_PATH}{@code <name>} on the classpath and instantiates it.
These resources are generated at build
+ * time by the {@code camel-package-maven-plugin} for every class annotated
with {@link Configurer}. Camel consults the
+ * resolver when configuring a component or endpoint from properties, using
the returned {@link PropertyConfigurer} to
+ * set options without reflection.
*
+ * @see PropertyConfigurer
+ * @see Configurer
* @since 3.1
*/
public interface ConfigurerResolver {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ConfigurerStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ConfigurerStrategy.java
index 17da829b3709..24ed6a825258 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ConfigurerStrategy.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ConfigurerStrategy.java
@@ -21,8 +21,17 @@ import java.util.List;
import java.util.Objects;
/**
- * Strategy for configurers.
+ * Utility class for managing the lifecycle of bootstrap-phase {@link
PropertyConfigurer} instances generated for
+ * {@link Configurer @Configurer(bootstrap = true)} types.
+ * <p/>
+ * During {@link org.apache.camel.CamelContext} startup, generated configurers
for bootstrap-only types (such as main
+ * configuration classes that are only configured once) are held in memory.
After the context has finished starting,
+ * calling {@link #clearBootstrapConfigurers()} releases those maps to reduce
the steady-state memory footprint. Modules
+ * register their own cleaner via {@link
#addBootstrapConfigurerClearer(Runnable)} during initialization so that the
+ * strategy does not need to know their internal data structures.
*
+ * @see Configurer
+ * @see PropertyConfigurer
* @since 3.7
*/
public abstract class ConfigurerStrategy {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/RouteController.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RouteController.java
index 6344dfe85ef6..d0ebb733241a 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/RouteController.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/RouteController.java
@@ -26,7 +26,22 @@ import org.apache.camel.ServiceStatus;
import org.apache.camel.StaticService;
/**
- * Controller for managing the lifecycle of all the {@link Route}'s.
+ * Central SPI for managing the start, stop, suspend, resume, and reload
lifecycle of all {@link Route}s in a
+ * {@link org.apache.camel.CamelContext}, as described in the
+ * <a href="https://camel.apache.org/manual/route-controller.html";>Route
Controller</a> documentation.
+ * <p/>
+ * The default implementation starts and stops routes synchronously in the
order determined by each route's
+ * {@code startupOrder} attribute and delegates graceful stopping to the
{@link ShutdownStrategy}. A more capable
+ * variant, {@link SupervisingRouteController}, can be enabled via {@link
#supervising()} to add asynchronous startup
+ * and exponential-backoff retry for routes that fail to start.
+ * <p/>
+ * End users interact with routes via {@link
org.apache.camel.CamelContext#getRouteController()} rather than this
+ * interface directly. Implementors providing a custom controller should also
implement
+ * {@link org.apache.camel.CamelContextAware} and register it before the
context starts.
+ *
+ * @see SupervisingRouteController
+ * @see ShutdownStrategy
+ * @see RouteStartupOrder
*/
public interface RouteController extends CamelContextAware, StaticService {
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/RoutePolicy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RoutePolicy.java
index d0318df80612..8615e8962b9d 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/RoutePolicy.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/RoutePolicy.java
@@ -20,13 +20,18 @@ import org.apache.camel.Exchange;
import org.apache.camel.Route;
/**
- * Policy for a {@link Route} which allows controlling the route at runtime.
+ * Per-route lifecycle hook that receives callbacks at each state change and
at the beginning and end of every
+ * {@link Exchange}, enabling dynamic control of route behaviour at runtime.
* <p/>
- * For example using the {@link
org.apache.camel.throttling.ThrottlingInflightRoutePolicy} to throttle the
{@link Route}
- * at runtime where it suspends and resume the {@link
org.apache.camel.Route#getConsumer()}.
+ * A {@code RoutePolicy} can suspend or resume a route's consumer in response
to external conditions, implement
+ * throttling by counting inflight exchanges (as {@link
org.apache.camel.throttling.ThrottlingInflightRoutePolicy}
+ * does), enforce time-window scheduling, or perform custom instrumentation.
Policies are attached to a route via the
+ * DSL {@code .routePolicy()} call or globally via a {@link
RoutePolicyFactory} registered on the context.
* <p/>
- * See also {@link Route} class javadoc about controlling the lifecycle of a
{@link Route}.
+ * See the <a href="https://camel.apache.org/manual/route-policy.html";>Route
Policy</a> documentation for usage patterns
+ * and built-in implementations.
*
+ * @see RoutePolicyFactory
* @see Route
*/
public interface RoutePolicy {
@@ -85,9 +90,9 @@ public interface RoutePolicy {
* Callback invoked when an {@link Exchange} is done being routed, where
it started from the given {@link Route}
* <p/>
* Notice this callback is invoked when the <b>Exchange</b> is done and
the {@link Route} is the route where the
- * {@link Exchange} was started. Most often its also the route where the
exchange is done. However its possible to
+ * {@link Exchange} was started. Most often its also the route where the
exchange is done. However, it's possible to
* route an {@link Exchange} to other routes using endpoints such as
<b>direct</b> or <b>seda</b>. Bottom line is
- * that the {@link Route} parameter may not be the endpoint route and thus
why we state its the starting route.
+ * that the {@link Route} parameter may not be the endpoint route and thus
why we state it's the starting route.
*
* @param route the route where the exchange started from
* @param exchange the created exchange
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/RoutePolicyFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RoutePolicyFactory.java
index 5b30d317c9d8..f248e53ec738 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/RoutePolicyFactory.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/RoutePolicyFactory.java
@@ -21,9 +21,18 @@ import org.apache.camel.NamedNode;
import org.jspecify.annotations.Nullable;
/**
- * A factory to create {@link org.apache.camel.spi.RoutePolicy} and assign to
routes automatically. Factories are
- * registered via {@link
org.apache.camel.CamelContext#addRoutePolicyFactory(RoutePolicyFactory)} and
are called for
- * every route during startup.
+ * Factory that creates a {@link RoutePolicy} instance for each route
automatically at startup, without requiring the
+ * policy to be declared per-route in the DSL.
+ * <p/>
+ * Factories are registered globally via {@link
org.apache.camel.CamelContext#addRoutePolicyFactory(RoutePolicyFactory)}
+ * and are called once per route during {@link org.apache.camel.CamelContext}
startup. Returning {@code null} from
+ * {@link #createRoutePolicy(org.apache.camel.CamelContext, String,
org.apache.camel.NamedNode)} opts that specific
+ * route out of the policy. This is useful for cross-cutting concerns such as
universal throttling, auditing, or metrics
+ * collection that should apply to all routes.
+ * <p/>
+ * See the <a href="https://camel.apache.org/manual/route-policy.html";>Route
Policy</a> documentation for examples.
+ *
+ * @see RoutePolicy
*/
public interface RoutePolicyFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/RouteStartupOrder.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RouteStartupOrder.java
index 4c235321966b..3ede711dc6df 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/RouteStartupOrder.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/RouteStartupOrder.java
@@ -23,8 +23,18 @@ import org.apache.camel.Route;
import org.apache.camel.Service;
/**
- * Information about a route to be started where we want to control the order
in which they are started by
- * {@link org.apache.camel.CamelContext}.
+ * Captures the resolved startup order and associated services for a {@link
Route}, used by
+ * {@link org.apache.camel.CamelContext} and {@link ShutdownStrategy} to
control start and shutdown sequencing.
+ * <p/>
+ * At startup, the context builds an ordered list of {@code RouteStartupOrder}
instances from each route's configured
+ * {@code startupOrder} attribute and passes it to the {@link
ShutdownStrategy} at shutdown time (in reverse order, by
+ * default). This allows routes with dependencies to be stopped before the
routes they depend on.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/configuring-route-startup-ordering-and-autostartup.html";>
Configuring
+ * Route Startup Ordering and Auto Startup</a> for details.
+ *
+ * @see ShutdownStrategy
+ * @see RouteController
*/
public interface RouteStartupOrder {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ShutdownStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ShutdownStrategy.java
index 50dbbf3d0244..e1a369e45967 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ShutdownStrategy.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ShutdownStrategy.java
@@ -24,23 +24,25 @@ import org.apache.camel.LoggingLevel;
import org.apache.camel.StaticService;
/**
- * Pluggable shutdown strategy executed during shutdown of Camel and the
active routes.
+ * Pluggable strategy that performs the actual <a
href="https://camel.apache.org/manual/graceful-shutdown.html";>graceful
+ * shutdown</a> sequence when a {@link CamelContext} is stopping.
* <p/>
- * Shutting down routes in a reliable and graceful manner is not a trivial
task. Therefore, Camel provides a pluggable
- * strategy allowing 3rd party to use their own strategy if needed.
+ * Graceful shutdown is non-trivial: Camel must stop all route consumers (so
no new messages enter) while keeping routes
+ * alive long enough to drain in-flight exchanges, including messages sitting
in in-memory queues (SEDA, etc.). The
+ * default implementation shuts down routes in reverse startup order (see
{@link RouteStartupOrder}), waits for
+ * in-flight exchanges to complete up to the configured {@link #setTimeout
timeout}, then forces shutdown if the timeout
+ * expires.
* <p/>
- * The shutdown strategy is <b>not</b> intended for Camel end users to use for
stopping routes. Instead, use
- * {@link RouteController} via {@link CamelContext}.
- * <p/>
- * The key problem is to stop the input consumers for the routes such that no
new messages is coming into Camel. But at
- * the same time still keep the routes running so the existing in flight
exchanges can still be run to completion. On
- * top of that there are some in memory components (such as SEDA) which may
have pending messages on its in memory queue
- * which we want to run to completion as well, otherwise they will get lost.
- * <p/>
- * Camel provides a default strategy which supports all that that can be used
as inspiration for your own strategy.
+ * This SPI is intended for framework and container integrators. End users who
need to stop individual routes should use
+ * {@link RouteController} via {@link CamelContext#getRouteController()}
instead. Per-route and per-consumer shutdown
+ * behaviour can be tuned via {@link org.apache.camel.ShutdownRoute} and
{@link org.apache.camel.ShutdownRunningTask}
+ * without replacing the strategy.
*
- * @see org.apache.camel.spi.ShutdownAware
* @see RouteController
+ * @see RouteStartupOrder
+ * @see org.apache.camel.ShutdownRoute
+ * @see org.apache.camel.ShutdownRunningTask
+ * @see org.apache.camel.spi.ShutdownAware
*/
public interface ShutdownStrategy extends StaticService {
@@ -152,7 +154,7 @@ public interface ShutdownStrategy extends StaticService {
* is happening. And during forced shutdown we want to avoid logging
errors/warnings et al. in the logs as a side
* effect of the forced timeout.
* <p/>
- * By default this is <tt>false</tt>
+ * By default, this is <tt>false</tt>
* <p/>
* Notice the suppression is a <i>best effort</i> as there may still be
some logs coming from 3rd party libraries
* and whatnot, which Camel cannot control.
@@ -166,7 +168,7 @@ public interface ShutdownStrategy extends StaticService {
* is happening. And during forced shutdown we want to avoid logging
errors/warnings et al. in the logs as a side
* effect of the forced timeout.
* <p/>
- * By default this is <tt>false</tt>
+ * By default, this is <tt>false</tt>
* <p/>
* Notice the suppression is a <i>best effort</i> as there may still be
some logs coming from 3rd party libraries
* and whatnot, which Camel cannot control.
@@ -199,7 +201,7 @@ public interface ShutdownStrategy extends StaticService {
void setShutdownRoutesInReverseOrder(boolean shutdownRoutesInReverseOrder);
/**
- * Whether to shutdown routes in reverse order than they were started.
+ * Whether to shut down routes in reverse order than they were started.
* <p/>
* This option is by default set to <tt>true</tt>.
*
@@ -223,7 +225,7 @@ public interface ShutdownStrategy extends StaticService {
boolean isLogInflightExchangesOnTimeout();
/**
- * Whether the shutdown strategy is forcing to shutdown
+ * Whether the shutdown strategy is forcing to shut down
*/
boolean isForceShutdown();
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/StartupCondition.java
b/core/camel-api/src/main/java/org/apache/camel/spi/StartupCondition.java
index fb8bddeb34c2..5014a15fce70 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/StartupCondition.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/StartupCondition.java
@@ -20,10 +20,15 @@ import org.apache.camel.CamelContext;
import org.jspecify.annotations.Nullable;
/**
- * Pluggable condition that must be accepted before Camel can continue
starting up.
- *
- * This can be used to let Camel wait for a specific file to be present, an
environment-variable, or some other custom
- * conditions.
+ * Pluggable gate evaluated repeatedly before {@link
org.apache.camel.CamelContext} finishes starting, allowing startup
+ * to be paused until an external prerequisite is satisfied.
+ * <p/>
+ * Camel polls each registered {@code StartupCondition} during the startup
sequence. If {@link #canContinue} returns
+ * {@code false}, startup waits and retries. If the condition is never
satisfied within the configured timeout the
+ * context aborts startup. Multiple conditions can be registered; all must be
satisfied for startup to proceed.
+ * <p/>
+ * Typical use cases include waiting for a readiness probe to pass, a required
file or directory to appear, an
+ * environment variable to be set, or a remote service to become reachable.
*
* @since 4.9
*/
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/StartupStepRecorder.java
b/core/camel-api/src/main/java/org/apache/camel/spi/StartupStepRecorder.java
index 8ec61537474e..f64b2a7bd4a1 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/StartupStepRecorder.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/StartupStepRecorder.java
@@ -23,9 +23,19 @@ import org.apache.camel.StaticService;
import org.jspecify.annotations.Nullable;
/**
- * To record {@link StartupStep} during startup to allow to capture diagnostic
information to help troubleshoot Camel
- * applications via various tooling such as Java Flight Recorder.
+ * Records named {@link StartupStep} spans during {@link
org.apache.camel.CamelContext} startup to capture timing and
+ * diagnostic information for troubleshooting and performance analysis.
+ * <p/>
+ * Each step is opened with {@link #beginStep} and closed with {@link
#endStep}, forming a tree of nested spans that
+ * mirrors the initialization call graph. The default implementation is a
no-op; the {@code camel-jfr} module provides
+ * an implementation that writes events to the Java Flight Recorder (JFR)
event stream, enabling correlation with JVM
+ * profiling data in tools such as JDK Mission Control.
+ * <p/>
+ * The recorder is started automatically when the context starts and stopped
(or kept running, depending on
+ * {@link #setStartupRecorderDuration}) once startup completes. Use {@link
#steps()} to iterate over captured steps
+ * after startup for programmatic analysis.
*
+ * @see StartupStep
* @since 3.8
*/
public interface StartupStepRecorder extends StaticService {
@@ -65,7 +75,7 @@ public interface StartupStepRecorder extends StaticService {
String getRecordingDir();
/**
- * Directory to store the recording. By default the current directory will
be used.
+ * Directory to store the recording. By default, the current directory
will be used.
*/
void setRecordingDir(String recordingDir);
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/SupervisingRouteController.java
b/core/camel-api/src/main/java/org/apache/camel/spi/SupervisingRouteController.java
index ba74db5b69c1..f6cd410c4c62 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/SupervisingRouteController.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/SupervisingRouteController.java
@@ -24,10 +24,19 @@ import org.apache.camel.util.backoff.BackOffTimer;
import org.jspecify.annotations.Nullable;
/**
- * A supervising capable {@link RouteController} that delays the startup of
the routes after the camel context startup
- * and takes control of starting the routes in a safe manner. This controller
is able to retry starting failing routes,
- * and have various options to configure settings for backoff between
restarting routes.
+ * Extension of {@link RouteController} that adds resilient, backoff-based
startup supervision for routes, as described
+ * in the <a
href="https://camel.apache.org/manual/route-controller.html";>Route
Controller</a> documentation.
+ * <p/>
+ * Unlike the default controller, this variant starts routes asynchronously
after the
+ * {@link org.apache.camel.CamelContext} has finished starting. Routes that
fail to start are retried using an
+ * exponential backoff schedule (configurable via {@link #setBackOffDelay},
{@link #setBackOffMaxAttempts}, and related
+ * setters). Routes can be selectively supervised via include/exclude patterns
matched against route id or endpoint URI.
+ * <p/>
+ * Failed routes can optionally be exposed as unhealthy via Camel's health
check infrastructure: set
+ * {@link #setUnhealthyOnExhausted} or {@link #setUnhealthyOnRestarting} to
control whether a route that is pending
+ * restart or has exhausted all attempts causes the application to report a
DOWN health status.
*
+ * @see RouteController
* @since 3.3
*/
public interface SupervisingRouteController extends RouteController {
@@ -40,7 +49,7 @@ public interface SupervisingRouteController extends
RouteController {
*
* The pattern is matching on route id, and endpoint uri for the route.
Multiple patterns can be separated by comma.
*
- * For example to include all kafka routes, you can say <tt>kafka:*</tt>.
And to include routes with specific route
+ * For example to include all Kafka routes, you can say <tt>kafka:*</tt>.
And to include routes with specific route
* ids <tt>myRoute,myOtherRoute</tt>. The pattern supports wildcards and
uses the matcher from
* org.apache.camel.support.PatternHelper#matchPattern.
*/
@@ -72,7 +81,7 @@ public interface SupervisingRouteController extends
RouteController {
long getInitialDelay();
/**
- * Initial delay in milli seconds before the route controller starts,
after CamelContext has been started.
+ * Initial delay in milliseconds before the route controller starts, after
CamelContext has been started.
*/
void setInitialDelay(long initialDelay);
