You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2026/06/08 05:17:06 UTC
(camel) branch main updated: CAMEL-23535: camel-api - batches 8-9: enhance Javadoc for registry, DI, and route lifecycle SPIs
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 <60...@users.noreply.github.com>
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);