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 d52ac05cdd5f CAMEL-23535: camel-api - enhance Javadoc for DI,
lifecycle, configurer, properties, and resource SPIs
d52ac05cdd5f is described below
commit d52ac05cdd5f0c583097814ccde376256e703343
Author: Adriano Machado <[email protected]>
AuthorDate: Sun Jun 21 02:00:32 2026 -0400
CAMEL-23535: camel-api - enhance Javadoc for DI, lifecycle, configurer,
properties, and resource SPIs
Batches 21-25: enhanced class-level and method-level Javadoc for 28
files in core/camel-api. Covers bean post-processing and DI SPIs,
CamelContext lifecycle event listeners, property configurer SPIs,
properties source SPIs, and resource loading SPIs. Each type received
an architecture paragraph with {@link} references, user-manual links
where applicable, and @see tags. Missing @param/@return tags added on
undocumented public methods. Also removed two dangling @see references
to non-existent OnCamelContextStart and OnCamelContextStop types.
Documentation-only; no production code or signatures changed.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Closes #24157
---
.../apache/camel/spi/CamelBeanPostProcessor.java | 27 +++++++++++++++++++++-
.../camel/spi/CamelBeanPostProcessorInjector.java | 14 +++++++++--
.../CamelDependencyInjectionAnnotationFactory.java | 13 +++++++++--
.../org/apache/camel/spi/DependencyStrategy.java | 10 ++++++--
.../spi/ExtendedPropertyConfigurerGetter.java | 11 +++++----
.../camel/spi/GeneratedPropertyConfigurer.java | 10 +++++++-
.../main/java/org/apache/camel/spi/Injector.java | 15 ++++++++++--
.../apache/camel/spi/LoadablePropertiesSource.java | 13 ++++++++---
.../org/apache/camel/spi/OnCamelContextEvent.java | 18 +++++++++++----
.../camel/spi/OnCamelContextInitialized.java | 15 +++++++++++-
.../camel/spi/OnCamelContextInitializing.java | 15 +++++++++++-
.../apache/camel/spi/OnCamelContextStarted.java | 15 +++++++++++-
.../apache/camel/spi/OnCamelContextStarting.java | 15 +++++++++++-
.../apache/camel/spi/OnCamelContextStopped.java | 15 +++++++++++-
.../apache/camel/spi/OnCamelContextStopping.java | 15 +++++++++++-
.../org/apache/camel/spi/PropertiesReload.java | 11 ++++++++-
.../apache/camel/spi/PropertiesResolvedValue.java | 10 +++++++-
.../org/apache/camel/spi/PropertiesSource.java | 19 +++++++++++----
.../apache/camel/spi/PropertiesSourceFactory.java | 26 +++++++++++++++------
.../org/apache/camel/spi/PropertyConfigurer.java | 14 ++++++++---
.../apache/camel/spi/PropertyConfigurerAware.java | 14 ++++++++---
.../apache/camel/spi/PropertyConfigurerGetter.java | 17 +++++++++-----
.../main/java/org/apache/camel/spi/Resource.java | 18 +++++++++++++--
.../java/org/apache/camel/spi/ResourceAware.java | 11 ++++++++-
.../java/org/apache/camel/spi/ResourceLoader.java | 9 +++++++-
.../java/org/apache/camel/spi/ResourceReload.java | 9 +++++++-
.../apache/camel/spi/ResourceReloadStrategy.java | 8 ++++++-
.../org/apache/camel/spi/ResourceResolver.java | 9 +++++++-
28 files changed, 335 insertions(+), 61 deletions(-)
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelBeanPostProcessor.java
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelBeanPostProcessor.java
index 2e3a90093b91..df58d7944dea 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelBeanPostProcessor.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelBeanPostProcessor.java
@@ -22,8 +22,25 @@ import org.apache.camel.BindToRegistry;
import org.jspecify.annotations.Nullable;
/**
- * Bean post processor.
+ * Processes beans as they are created or registered, applying Camel's
annotation-based dependency injection.
+ * <p/>
+ * For every bean it inspects, the post processor wires up the Camel injection
annotations such as
+ * {@link org.apache.camel.EndpointInject}, {@link org.apache.camel.Produce},
{@link org.apache.camel.Consume},
+ * {@link org.apache.camel.BeanInject}, and {@link
org.apache.camel.PropertyInject}, and binds
+ * {@link org.apache.camel.BindToRegistry} beans into the {@link Registry}.
Processing runs in two phases,
+ * {@link #postProcessBeforeInitialization(Object, String)} and {@link
#postProcessAfterInitialization(Object, String)},
+ * mirroring the well-known Spring BeanPostProcessor lifecycle so a bean can
be enriched both before and after its own
+ * init callbacks. Runtimes that already perform their own injection (Spring,
Quarkus, CDI) supply their own
+ * implementations, while the default runtime uses reflection. Custom
injection for 3rd-party annotations can be plugged
+ * in via {@link CamelBeanPostProcessorInjector}, and {@link
CamelDependencyInjectionAnnotationFactory} controls how
+ * {@link org.apache.camel.BindToRegistry} beans are bound. Bean post
processing can be disabled via
+ * {@link #setEnabled(boolean)} for runtimes that do not use these Camel
features.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/bean-injection.html";>Bean
Injection</a> in the Camel user manual.
*
+ * @see CamelBeanPostProcessorInjector
+ * @see CamelDependencyInjectionAnnotationFactory
+ * @see Injector
* @since 3.0
*/
public interface CamelBeanPostProcessor {
@@ -71,10 +88,18 @@ public interface CamelBeanPostProcessor {
// noop
}
+ /**
+ * Whether bean post processing is enabled.
+ */
default boolean isEnabled() {
return true;
}
+ /**
+ * Sets whether to unbind any existing beans before binding a bean to the
registry.
+ *
+ * @see #isUnbindEnabled()
+ */
default void setUnbindEnabled(boolean unbindEnabled) {
// noop
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelBeanPostProcessorInjector.java
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelBeanPostProcessorInjector.java
index 6fc1c679ac63..90e0681f7dc7 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelBeanPostProcessorInjector.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelBeanPostProcessorInjector.java
@@ -22,9 +22,19 @@ import java.lang.reflect.Method;
import org.jspecify.annotations.Nullable;
/**
- * Used for custom injection when doing {@link CamelBeanPostProcessor} bean
post-processing. Can be used to support
- * 3rd-party annotations for dependency injections.
+ * Pluggable injector that participates in {@link CamelBeanPostProcessor} bean
post-processing to support custom,
+ * typically 3rd-party, dependency-injection annotations.
+ * <p/>
+ * When the {@link CamelBeanPostProcessor} scans a bean it invokes every
registered injector for each field
+ * ({@link #onFieldInject(Field, Object, String)}) and method ({@link
#onMethodInject(Method, Object, String)}),
+ * allowing the injector to detect its own annotations and inject the
appropriate values. This is how integrations layer
+ * support for annotations beyond the built-in Camel ones (for example Spring
or Quarkus annotations) on top of the
+ * standard post processor. Injectors are registered through
+ * {@link
CamelBeanPostProcessor#addCamelBeanPostProjectInjector(CamelBeanPostProcessorInjector)}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/bean-injection.html";>Bean
Injection</a> in the Camel user manual.
*
+ * @see CamelBeanPostProcessor
* @since 3.16
*/
public interface CamelBeanPostProcessorInjector {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelDependencyInjectionAnnotationFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelDependencyInjectionAnnotationFactory.java
index e1c7f515a8e0..e78e24956036 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelDependencyInjectionAnnotationFactory.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelDependencyInjectionAnnotationFactory.java
@@ -17,9 +17,18 @@
package org.apache.camel.spi;
/**
- * A factory which performs the task from Camel dependency injection
annotations on a field, property or method
- * parameter of a specified type.
+ * Factory that creates the task carrying out a Camel dependency-injection
annotation, such as binding a
+ * {@link org.apache.camel.BindToRegistry} bean into the {@link Registry}.
+ * <p/>
+ * During {@link CamelBeanPostProcessor} bean post-processing, when a {@link
org.apache.camel.BindToRegistry} annotation
+ * is found this factory produces a {@link Runnable} that performs the actual
binding, including any optional init and
+ * destroy methods. Decoupling the binding into a task lets runtimes (such as
Spring or Quarkus) control exactly when
+ * and how beans are registered, rather than binding eagerly during the scan.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/bean-integration.html";>Bean
Integration</a> in the Camel user manual.
*
+ * @see CamelBeanPostProcessor
+ * @see org.apache.camel.BindToRegistry
* @since 3.16
*/
public interface CamelDependencyInjectionAnnotationFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/DependencyStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/DependencyStrategy.java
index 40c410b2aef7..b5adca1f50ee 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/DependencyStrategy.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/DependencyStrategy.java
@@ -17,8 +17,14 @@
package org.apache.camel.spi;
/**
- * Strategy when 3rd party dependencies are detected during loading routes.
For example when loading YAML DSL routes for
- * Camel K where dependencies are listed in the YAML file.
+ * Strategy notified when a 3rd-party dependency is detected while loading
routes.
+ * <p/>
+ * Some DSLs declare external dependencies inline; for example YAML DSL routes
(as used by Camel K) can list Maven
+ * coordinates that the route needs. As such routes are loaded, each detected
dependency is reported through
+ * {@link #onDependency(String)} so the runtime can react, for instance by
downloading the artifact and adding it to the
+ * classpath. The dependency is expressed as a resolver URI such as {@code
mvn:com.foo/bar/1.2.3}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/camel-jbang.html";>Camel
CLI</a> in the Camel user manual.
*
* @since 3.16
*/
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ExtendedPropertyConfigurerGetter.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ExtendedPropertyConfigurerGetter.java
index e9912725d837..fd0528e70979 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ExtendedPropertyConfigurerGetter.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ExtendedPropertyConfigurerGetter.java
@@ -19,15 +19,16 @@ package org.apache.camel.spi;
import java.util.Map;
/**
- * A marker interface to identify the object as being a configurer which can
provide details about the options the
- * configurer supports.
+ * Extends {@link PropertyConfigurerGetter} with the ability to enumerate
every option a target supports.
* <p/>
- * This is used in Camel to have fast property configuration of Camel
components & endpoints, and for EIP patterns as
- * well.
+ * In addition to inspecting individual options, {@link
#getAllOptions(Object)} returns the full map of option name to
+ * class type for a target. This is used primarily by API-based components and
is only available while the
+ * {@link org.apache.camel.CamelContext} is bootstrapping.
* <p/>
- * This is used by API based components
+ * See <a
href="https://camel.apache.org/manual/property-binding.html";>Property
Binding</a> in the Camel user manual.
*
* @see PropertyConfigurer
+ * @see PropertyConfigurerGetter
* @since 3.7
*/
public interface ExtendedPropertyConfigurerGetter extends
PropertyConfigurerGetter {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/GeneratedPropertyConfigurer.java
b/core/camel-api/src/main/java/org/apache/camel/spi/GeneratedPropertyConfigurer.java
index 25e8dd878d24..03b7b9223252 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/GeneratedPropertyConfigurer.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/GeneratedPropertyConfigurer.java
@@ -17,8 +17,16 @@
package org.apache.camel.spi;
/**
- * A auto generated {@link PropertyConfigurer} for fast configuration of Camel
components & endpoints.
+ * Marker for a {@link PropertyConfigurer} that Camel generates at build time
for fast configuration of components and
+ * endpoints.
+ * <p/>
+ * Implementations are produced by the Camel tooling from a type's options,
providing reflection-free property binding
+ * during bootstrap. Application code does not implement this directly; it is
generated alongside the component or
+ * endpoint it configures.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/property-binding.html";>Property
Binding</a> in the Camel user manual.
*
+ * @see PropertyConfigurer
* @since 3.0
*/
public interface GeneratedPropertyConfigurer extends PropertyConfigurer {
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/Injector.java
b/core/camel-api/src/main/java/org/apache/camel/spi/Injector.java
index 636090a4ccf6..899c73348e1e 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/Injector.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/Injector.java
@@ -17,8 +17,19 @@
package org.apache.camel.spi;
/**
- * A pluggable strategy for creating and possibly dependency injecting objects
which could be implemented using straight
- * forward reflection or using Spring or Quarkus to perform dependency
injection.
+ * Pluggable strategy for instantiating objects, optionally performing
dependency injection as part of creation.
+ * <p/>
+ * Camel uses the injector whenever it needs to create an instance of a
user-supplied type (beans, processors, type
+ * converters, and so on) so that the surrounding runtime controls
instantiation. The default implementation uses
+ * straightforward reflection, while runtimes such as Spring or Quarkus
provide implementations that resolve and inject
+ * dependencies through their own container. The {@link #newInstance(Class)}
overloads support creation via a public
+ * no-arg constructor, a static factory method, a factory class, and with or
without bean post processing applied by
+ * {@link CamelBeanPostProcessor}. {@link #supportsAutoWiring()} reports
whether the injector can autowire constructor
+ * dependencies.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/bean-integration.html";>Bean
Integration</a> in the Camel user manual.
+ *
+ * @see CamelBeanPostProcessor
*/
public interface Injector {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/LoadablePropertiesSource.java
b/core/camel-api/src/main/java/org/apache/camel/spi/LoadablePropertiesSource.java
index 2247a495ba7a..1bb0fdbc5b91 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/LoadablePropertiesSource.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/LoadablePropertiesSource.java
@@ -22,11 +22,18 @@ import java.util.function.Predicate;
import org.apache.camel.Ordered;
/**
- * A source for properties that can be loaded all at once during
initialization, such as loading .properties files.
+ * A {@link PropertiesSource} whose properties can be loaded all at once
during initialization, such as a .properties
+ * file.
* <p/>
- * A source can implement {@link Ordered} to control the ordering of which
sources are used by the Camel properties
- * component. The source with the highest precedence (the lowest number) will
be used first.
+ * In addition to looking up single values, a loadable source can return its
entire set of properties via
+ * {@link #loadProperties()} (optionally filtered by key) and can re-read them
from the location to support reloading.
+ * Like any source it may implement {@link Ordered} to control precedence; the
source with the highest precedence (the
+ * lowest number) is used first.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/using-propertyplaceholder.html";>Using
PropertyPlaceholder</a> in the
+ * Camel user manual.
*
+ * @see PropertiesSource
* @since 3.0
*/
public interface LoadablePropertiesSource extends PropertiesSource {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextEvent.java
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextEvent.java
index 638085c87488..63469b711356 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextEvent.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextEvent.java
@@ -17,17 +17,25 @@
package org.apache.camel.spi;
/**
- * Marker interface used to make it easy to discover {@link
org.apache.camel.CamelContext} related event handlers from
- * the registry.
+ * Marker interface for event handlers that react to {@link
org.apache.camel.CamelContext} lifecycle phases.
+ * <p/>
+ * Implementations are placed in the {@link Registry} and discovered by Camel
during bootstrap, then invoked as the
+ * context moves through its lifecycle: initializing, initialized, starting,
started, stopping, and stopped. Each phase
+ * has its own sub-interface ({@link OnCamelContextInitializing}, {@link
OnCamelContextInitialized},
+ * {@link OnCamelContextStarting}, {@link OnCamelContextStarted}, {@link
OnCamelContextStopping},
+ * {@link OnCamelContextStopped}) which a handler implements to receive that
specific callback; a single class may
+ * implement several of them. This is a lightweight, registry-driven
alternative to {@link LifecycleStrategy} for code
+ * that only needs to hook into context startup or shutdown.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/lifecycle.html";>Lifecycle</a>
in the Camel user manual.
*
* @see OnCamelContextInitializing
* @see OnCamelContextInitialized
- * @see OnCamelContextStart
* @see OnCamelContextStarting
* @see OnCamelContextStarted
- * @see OnCamelContextStop
- * @see OnCamelContextStopped
* @see OnCamelContextStopping
+ * @see OnCamelContextStopped
+ * @see LifecycleStrategy
* @since 3.4
*/
public interface OnCamelContextEvent {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextInitialized.java
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextInitialized.java
index 40a8acfbd469..54f942c75689 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextInitialized.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextInitialized.java
@@ -19,11 +19,24 @@ package org.apache.camel.spi;
import org.apache.camel.CamelContext;
/**
- * Notification on an initialized a {@link CamelContext}.
+ * Event handler invoked after the {@link CamelContext} has been initialized,
before it is started.
+ * <p/>
+ * Implementations are registered in the {@link Registry} and discovered by
Camel during bootstrap. At this point all
+ * routes and services have been initialized but not yet started, so this
phase suits inspection or final adjustments
+ * that depend on a fully initialized context. For the full set of lifecycle
callbacks see {@link OnCamelContextEvent}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/lifecycle.html";>Lifecycle</a>
in the Camel user manual.
*
+ * @see OnCamelContextEvent
* @since 3.4
*/
@FunctionalInterface
public interface OnCamelContextInitialized extends OnCamelContextEvent {
+
+ /**
+ * Callback invoked after the {@link CamelContext} has been initialized.
+ *
+ * @param context the camel context
+ */
void onContextInitialized(CamelContext context);
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextInitializing.java
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextInitializing.java
index 6fdff65af6b1..83d1dbed3c8a 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextInitializing.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextInitializing.java
@@ -19,11 +19,24 @@ package org.apache.camel.spi;
import org.apache.camel.CamelContext;
/**
- * Notification on initializing a {@link CamelContext}.
+ * Event handler invoked while the {@link CamelContext} is initializing,
before it is started.
+ * <p/>
+ * Implementations are registered in the {@link Registry} and discovered by
Camel during bootstrap. This phase runs
+ * once, early in the lifecycle, making it a good place for setup that must
complete before routes and services are
+ * started. For the full set of lifecycle callbacks see {@link
OnCamelContextEvent}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/lifecycle.html";>Lifecycle</a>
in the Camel user manual.
*
+ * @see OnCamelContextEvent
* @since 3.5
*/
@FunctionalInterface
public interface OnCamelContextInitializing extends OnCamelContextEvent {
+
+ /**
+ * Callback invoked while the {@link CamelContext} is initializing.
+ *
+ * @param context the camel context
+ */
void onContextInitializing(CamelContext context);
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStarted.java
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStarted.java
index 6e0c3d1e8ef4..a1a8d7e91521 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStarted.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStarted.java
@@ -19,11 +19,24 @@ package org.apache.camel.spi;
import org.apache.camel.CamelContext;
/**
- * Notification on a started {@link CamelContext}.
+ * Event handler invoked after the {@link CamelContext} has fully started and
its routes are running.
+ * <p/>
+ * Implementations are registered in the {@link Registry} and discovered by
Camel during bootstrap. By the time this
+ * callback fires the context is operational, making it a good place for
actions that require a running context, such as
+ * triggering an initial message. For the full set of lifecycle callbacks see
{@link OnCamelContextEvent}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/lifecycle.html";>Lifecycle</a>
in the Camel user manual.
*
+ * @see OnCamelContextEvent
* @since 3.5
*/
@FunctionalInterface
public interface OnCamelContextStarted extends OnCamelContextEvent {
+
+ /**
+ * Callback invoked after the {@link CamelContext} has been started.
+ *
+ * @param context the camel context
+ */
void onContextStarted(CamelContext context);
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStarting.java
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStarting.java
index 9f37f84c317a..6843d669d405 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStarting.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStarting.java
@@ -19,11 +19,24 @@ package org.apache.camel.spi;
import org.apache.camel.CamelContext;
/**
- * Notification on starting a {@link CamelContext}.
+ * Event handler invoked while the {@link CamelContext} is starting, before it
has fully started.
+ * <p/>
+ * Implementations are registered in the {@link Registry} and discovered by
Camel during bootstrap. This callback fires
+ * as the context begins starting its routes and services, suiting work that
must run just before the context becomes
+ * operational. For the full set of lifecycle callbacks see {@link
OnCamelContextEvent}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/lifecycle.html";>Lifecycle</a>
in the Camel user manual.
*
+ * @see OnCamelContextEvent
* @since 3.5
*/
@FunctionalInterface
public interface OnCamelContextStarting extends OnCamelContextEvent {
+
+ /**
+ * Callback invoked while the {@link CamelContext} is starting.
+ *
+ * @param context the camel context
+ */
void onContextStarting(CamelContext context);
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStopped.java
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStopped.java
index 382e08de9d86..27cedbf04e8b 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStopped.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStopped.java
@@ -19,11 +19,24 @@ package org.apache.camel.spi;
import org.apache.camel.CamelContext;
/**
- * Notification on a stopped {@link CamelContext}.
+ * Event handler invoked after the {@link CamelContext} has fully stopped.
+ * <p/>
+ * Implementations are registered in the {@link Registry} and discovered by
Camel during bootstrap. By the time this
+ * callback fires all routes and services have been shut down, making it the
place for final cleanup once the context is
+ * no longer operational. For the full set of lifecycle callbacks see {@link
OnCamelContextEvent}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/lifecycle.html";>Lifecycle</a>
in the Camel user manual.
*
+ * @see OnCamelContextEvent
* @since 3.5
*/
@FunctionalInterface
public interface OnCamelContextStopped extends OnCamelContextEvent {
+
+ /**
+ * Callback invoked after the {@link CamelContext} has been stopped.
+ *
+ * @param context the camel context
+ */
void onContextStopped(CamelContext context);
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStopping.java
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStopping.java
index bfd0868c3a09..3141dd639350 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStopping.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/OnCamelContextStopping.java
@@ -19,11 +19,24 @@ package org.apache.camel.spi;
import org.apache.camel.CamelContext;
/**
- * Notification on stopping a {@link CamelContext}.
+ * Event handler invoked while the {@link CamelContext} is stopping, before it
has fully stopped.
+ * <p/>
+ * Implementations are registered in the {@link Registry} and discovered by
Camel during bootstrap. This callback fires
+ * as the context begins shutting down its routes and services, suiting
cleanup that must run while the context is still
+ * partly operational. For the full set of lifecycle callbacks see {@link
OnCamelContextEvent}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/lifecycle.html";>Lifecycle</a>
in the Camel user manual.
*
+ * @see OnCamelContextEvent
* @since 3.5
*/
@FunctionalInterface
public interface OnCamelContextStopping extends OnCamelContextEvent {
+
+ /**
+ * Callback invoked while the {@link CamelContext} is stopping.
+ *
+ * @param context the camel context
+ */
void onContextStopping(CamelContext context);
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesReload.java
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesReload.java
index a9c5d07a4b68..457319c014ad 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesReload.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesReload.java
@@ -19,8 +19,17 @@ package org.apache.camel.spi;
import java.util.Properties;
/**
- * Listener for re-loading a {@link java.util.Properties} such as a Camel
route.
+ * Listener notified when a {@link java.util.Properties} source is re-loaded
at runtime, for example after a properties
+ * file changes.
+ * <p/>
+ * When live reloading is enabled, the {@link PropertiesComponent} invokes
{@link #onReload(String, Properties)} with
+ * the resource name and the freshly loaded properties, allowing Camel to
react to configuration changes without a
+ * restart.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/using-propertyplaceholder.html";>Using
PropertyPlaceholder</a> in the
+ * Camel user manual.
*
+ * @see PropertiesComponent
* @since 4.0
*/
@FunctionalInterface
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesResolvedValue.java
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesResolvedValue.java
index 2e090c1c9d13..74f8b264f48b 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesResolvedValue.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesResolvedValue.java
@@ -19,8 +19,16 @@ package org.apache.camel.spi;
import org.jspecify.annotations.Nullable;
/**
- * Data about a {@link PropertiesComponent} property placeholder that has been
resolved to a value by Camel.
+ * Captures how a single {@link PropertiesComponent} property placeholder was
resolved, for inspection and tooling.
+ * <p/>
+ * Each instance records the placeholder {@code name}, the {@code
originalValue} (the raw placeholder expression), the
+ * resolved {@code value}, any {@code defaultValue} that applied, and the
{@code source} that provided the value. Camel
+ * tracks these so the resolved configuration can be reviewed, for example by
the developer console or diagnostics.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/using-propertyplaceholder.html";>Using
PropertyPlaceholder</a> in the
+ * Camel user manual.
*
+ * @see PropertiesComponent
* @since 4.9
*/
public record PropertiesResolvedValue(String name, String originalValue,
String value, @Nullable String defaultValue,
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesSource.java
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesSource.java
index 29c047a528e8..490b489e457b 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesSource.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesSource.java
@@ -20,17 +20,28 @@ import org.apache.camel.Ordered;
import org.jspecify.annotations.Nullable;
/**
- * A source for properties.
+ * A source of property values for the Camel {@link PropertiesComponent} when
resolving property placeholders.
* <p/>
- * A source can implement {@link Ordered} to control the ordering of which
sources are used by the Camel properties
- * component. The source with the highest precedence (the lowest number) will
be used first.
+ * The properties component consults all registered sources (system
properties, environment variables, .properties
+ * files, beans, vaults, and so on) to resolve a placeholder. A source can
implement {@link Ordered} to control its
+ * precedence; the source with the highest precedence (the lowest number) is
consulted first. Sources whose properties
+ * can be loaded eagerly in bulk implement {@link LoadablePropertiesSource},
and the built-in sources are created via
+ * {@link PropertiesSourceFactory}.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/using-propertyplaceholder.html";>Using
PropertyPlaceholder</a> in the
+ * Camel user manual.
*
+ * @see PropertiesComponent
+ * @see LoadablePropertiesSource
+ * @see PropertiesSourceFactory
* @since 3.0
*/
public interface PropertiesSource {
/**
- * Name of properties source
+ * The name of this properties source.
+ *
+ * @return the source name
*/
String getName();
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesSourceFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesSourceFactory.java
index fcad90f4d6a7..ee214cb0ac83 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesSourceFactory.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertiesSourceFactory.java
@@ -17,30 +17,42 @@
package org.apache.camel.spi;
/**
- * Factory for creating out of the box {@link PropertiesSource}.
+ * Factory for creating the built-in {@link PropertiesSource} implementations
used by the {@link PropertiesComponent}.
+ * <p/>
+ * Given a property location, the factory produces the appropriate source:
file-based, classpath-based, or one backed by
+ * a {@link java.util.Properties} bean looked up by reference in the {@link
Registry}. The properties component uses
+ * this to turn configured locations into active sources during initialization.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/using-propertyplaceholder.html";>Using
PropertyPlaceholder</a> in the
+ * Camel user manual.
*
+ * @see PropertiesSource
+ * @see PropertiesComponent
* @since 4.0
*/
public interface PropertiesSourceFactory {
/**
- * New file based {@link PropertiesSource}
+ * Creates a new file based {@link PropertiesSource}.
*
- * @param location location of the file
+ * @param location location of the file
+ * @return the properties source
*/
PropertiesSource newFilePropertiesSource(String location);
/**
- * New classpath based {@link PropertiesSource}
+ * Creates a new classpath based {@link PropertiesSource}.
*
- * @param location location of the file in the classpath
+ * @param location location of the file in the classpath
+ * @return the properties source
*/
PropertiesSource newClasspathPropertiesSource(String location);
/**
- * New ref based {@link PropertiesSource}
+ * Creates a new ref based {@link PropertiesSource}.
*
- * @param ref id for the {@link java.util.Properties} bean.
+ * @param ref id for the {@link java.util.Properties} bean
+ * @return the properties source
*/
PropertiesSource newRefPropertiesSource(String ref);
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurer.java
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurer.java
index 443091e02a94..37f29297699a 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurer.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurer.java
@@ -19,12 +19,20 @@ package org.apache.camel.spi;
import org.apache.camel.CamelContext;
/**
- * A marker interface to identify the object as being configurable via a
configurer class.
+ * Configures a single property on a target object (such as a {@link
org.apache.camel.Component},
+ * {@link org.apache.camel.Endpoint}, or EIP) without using reflection.
* <p/>
- * This is used in Camel to have fast property configuration of Camel
components & endpoints, and for EIP patterns as
- * well.
+ * Camel generates a {@code PropertyConfigurer} implementation at build time
for each configurable type, giving fast,
+ * reflection-free property binding during bootstrap. The {@link #configure}
method sets one named property and reports
+ * whether the property was recognized, with optional case-insensitive name
matching. Generated configurers implement
+ * {@link GeneratedPropertyConfigurer}, types that expose their configurer
implement {@link PropertyConfigurerAware},
+ * and configurers that can additionally describe their options implement
{@link PropertyConfigurerGetter}.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/property-binding.html";>Property
Binding</a> in the Camel user manual.
*
+ * @see GeneratedPropertyConfigurer
* @see PropertyConfigurerGetter
+ * @see PropertyConfigurerAware
* @since 3.0
*/
public interface PropertyConfigurer {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurerAware.java
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurerAware.java
index a07abb75e9e8..8f093ccda7f0 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurerAware.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurerAware.java
@@ -19,16 +19,24 @@ package org.apache.camel.spi;
import org.jspecify.annotations.Nullable;
/**
- * An interface to represent an object which is capable of configuring via
{@link PropertyConfigurer}.
+ * Implemented by objects that can supply the {@link PropertyConfigurer} for a
given bean instance.
+ * <p/>
+ * This lets Camel obtain the fast, reflection-free configurer for a target
without looking it up separately, for
+ * example when a {@link org.apache.camel.Component} provides the configurer
for the endpoints it creates. The returned
+ * configurer is then used to bind properties during bootstrap.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/property-binding.html";>Property
Binding</a> in the Camel user manual.
*
+ * @see PropertyConfigurer
* @since 3.0
*/
public interface PropertyConfigurerAware {
/**
- * Gets the configurer.
+ * Gets the {@link PropertyConfigurer} for the given bean instance.
*
- * @param instance the bean instance
+ * @param instance the bean instance
+ * @return the configurer, or <tt>null</tt> if none is available
*/
@Nullable
PropertyConfigurer getPropertyConfigurer(Object instance);
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurerGetter.java
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurerGetter.java
index 14fd420575de..76e8ee4a8c44 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurerGetter.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/PropertyConfigurerGetter.java
@@ -19,11 +19,15 @@ package org.apache.camel.spi;
import org.jspecify.annotations.Nullable;
/**
- * A marker interface to identify the object as being a configurer which can
provide details about the options the
- * configurer supports.
+ * Extension of the configurer SPI that, in addition to setting properties,
can describe the options a target supports.
* <p/>
- * This is used in Camel to have fast property configuration of Camel
components & endpoints, and for EIP patterns as
- * well.
+ * Where {@link PropertyConfigurer} only writes property values, a getter can
report each option's type
+ * ({@link #getOptionType}), read the current value ({@link #getOptionValue}),
resolve the element type of collection
+ * options ({@link #getCollectionValueType}), and list autowired options
({@link #getAutowiredNames}). Generated
+ * configurers typically implement this so tooling and the property-binding
engine can introspect components and
+ * endpoints. {@link ExtendedPropertyConfigurerGetter} adds enumeration of all
options.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/property-binding.html";>Property
Binding</a> in the Camel user manual.
*
* @see PropertyConfigurer
* @see ExtendedPropertyConfigurerGetter
@@ -34,8 +38,9 @@ public interface PropertyConfigurerGetter {
/**
* Gets the option class type.
*
- * @param name the property name
- * @return the class type, or <tt>null</tt> if no option exists with
the name
+ * @param name the property name
+ * @param ignoreCase whether to ignore case for matching the property name
+ * @return the class type, or <tt>null</tt> if no option exists
with the name
*/
@Nullable
Class<?> getOptionType(String name, boolean ignoreCase);
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/Resource.java
b/core/camel-api/src/main/java/org/apache/camel/spi/Resource.java
index fbf1b9694485..47fd0be35981 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/Resource.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/Resource.java
@@ -29,24 +29,38 @@ import java.nio.charset.StandardCharsets;
import org.jspecify.annotations.Nullable;
/**
- * Describe a resource, such as a file or class path resource.
+ * Describes a loadable resource such as a file, classpath entry, or HTTP URL.
+ * <p/>
+ * A resource abstracts over its backing location: it exposes the {@link
#getScheme() scheme} (file, classpath, http,
+ * and so on), the {@link #getLocation() location}, whether it {@link
#exists()}, and provides fresh
+ * {@link #getInputStream() streams} or {@link #getReader() readers} on each
call. Camel loads routes, scripts, and
+ * other artifacts through resources. Instances are obtained from a {@link
ResourceLoader}, which delegates to a
+ * scheme-specific {@link ResourceResolver}.
*
+ * @see ResourceLoader
+ * @see ResourceResolver
* @since 3.8
*/
public interface Resource {
/**
- * The scheme of the resource such as file, classpath, http
+ * The scheme of the resource such as file, classpath, or http.
+ *
+ * @return the scheme
*/
String getScheme();
/**
* The location of the resource.
+ *
+ * @return the location
*/
String getLocation();
/**
* Whether this resource exists.
+ *
+ * @return <tt>true</tt> if the resource exists
*/
boolean exists();
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ResourceAware.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ResourceAware.java
index 07f1453cd196..144523d71d76 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ResourceAware.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ResourceAware.java
@@ -19,8 +19,13 @@ package org.apache.camel.spi;
import org.jspecify.annotations.Nullable;
/**
- * An interface to represent an object which wishes to be injected with the
{@link Resource}
+ * Implemented by objects that want the {@link Resource} they originate from
to be injected into them.
+ * <p/>
+ * When Camel creates an object from a resource (for example a route loaded
from a file), it sets the originating
+ * {@link Resource} on the object if it implements this interface, so the
object can later refer back to where it came
+ * from. The {@link #trySetResource(Object, Resource)} helper performs this
injection conditionally.
*
+ * @see Resource
* @since 3.17
*/
public interface ResourceAware {
@@ -38,12 +43,16 @@ public interface ResourceAware {
/**
* Gets the {@link Resource}.
+ *
+ * @return the resource, or <tt>null</tt> if none is set
*/
@Nullable
Resource getResource();
/**
* Sets the {@link Resource}.
+ *
+ * @param resource the resource
*/
void setResource(Resource resource);
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ResourceLoader.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ResourceLoader.java
index 503c4e9b0a17..22754fd57848 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ResourceLoader.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ResourceLoader.java
@@ -19,8 +19,15 @@ package org.apache.camel.spi;
import org.apache.camel.CamelContextAware;
/**
- * SPI for loading resources.
+ * SPI for loading a {@link Resource} from a URI.
+ * <p/>
+ * The resource loader is the entry point Camel uses to turn a location (such
as {@code file:routes.yaml} or
+ * {@code classpath:rules.txt}) into a {@link Resource}. It selects the
appropriate scheme-specific
+ * {@link ResourceResolver} to perform the actual resolution. A single loader
is registered per
+ * {@link org.apache.camel.CamelContext} under the {@value #FACTORY} factory
key.
*
+ * @see Resource
+ * @see ResourceResolver
* @since 3.9
*/
public interface ResourceLoader extends CamelContextAware {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ResourceReload.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ResourceReload.java
index 7b49a36636b8..49ae330e50a9 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ResourceReload.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ResourceReload.java
@@ -17,8 +17,15 @@
package org.apache.camel.spi;
/**
- * Listener for re-loading a {@link Resource} such as a Camel route.
+ * Listener notified when a {@link Resource} is re-loaded at runtime, for
example after a route file changes.
+ * <p/>
+ * When live reloading is enabled, the {@link ResourceReloadStrategy} invokes
{@link #onReload(String, Resource)} with
+ * the resource name and the reloaded {@link Resource}, allowing Camel to
update routes without a restart.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/route-reload.html";>Route
Reload</a> in the Camel user manual.
*
+ * @see ResourceReloadStrategy
+ * @see Resource
* @since 3.14
*/
@FunctionalInterface
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ResourceReloadStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ResourceReloadStrategy.java
index ba76fe4aafcc..cce79a7f7bb2 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ResourceReloadStrategy.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ResourceReloadStrategy.java
@@ -17,7 +17,13 @@
package org.apache.camel.spi;
/**
- * SPI strategy for reloading {@link Resource} in an existing running {@link
org.apache.camel.CamelContext}
+ * SPI strategy for reloading {@link Resource}s in an already running {@link
org.apache.camel.CamelContext}.
+ * <p/>
+ * The strategy watches resources (typically route files) and, on change,
notifies its configured {@link ResourceReload}
+ * listener so Camel can apply the updated definitions live. It is the
resource-oriented counterpart to
+ * {@link ContextReloadStrategy} and builds on the generic {@link
ReloadStrategy}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/route-reload.html";>Route
Reload</a> in the Camel user manual.
*
* @see ContextReloadStrategy
* @see ResourceReload
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ResourceResolver.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ResourceResolver.java
index 030ffe8715ba..03a112563b8c 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ResourceResolver.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ResourceResolver.java
@@ -21,8 +21,15 @@ import org.apache.camel.StaticService;
import org.jspecify.annotations.Nullable;
/**
- * SPI for loading resources.
+ * SPI for resolving a {@link Resource} for a specific URI scheme.
+ * <p/>
+ * Each resolver handles a single {@link #getSupportedScheme() scheme} (such
as file, classpath, http) and turns a
+ * location into a {@link Resource}, or returns {@code null} if it cannot. The
{@link ResourceLoader} dispatches to the
+ * matching resolver; scheme-specific resolvers are discovered from {@value
#FACTORY_PATH}, with an optional
+ * {@link #FALLBACK_RESOURCE_RESOLVER fallback} used when no scheme matches.
*
+ * @see Resource
+ * @see ResourceLoader
* @since 3.9
*/
public interface ResourceResolver extends StaticService, CamelContextAware {
