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 4bafd4bbac3e CAMEL-23535: camel-api - enhance Javadoc for customizer,
reload, data-type, marker, and interceptor SPIs
4bafd4bbac3e is described below
commit 4bafd4bbac3ede4356bfbae216e024cc749a5ae6
Author: Adriano Machado <[email protected]>
AuthorDate: Sun Jun 21 03:30:22 2026 -0400
CAMEL-23535: camel-api - enhance Javadoc for customizer, reload, data-type,
marker, and interceptor SPIs
Batches 26-30: enhanced class-level and method-level Javadoc for 24
files in core/camel-api (org.apache.camel.spi). Covers customizer SPIs,
context tracking and reload SPIs, data type and transformation SPIs,
id/group marker SPIs, and interceptor SPIs. Each type received an
architecture paragraph with {@link} references, user-manual links where
applicable, and @see cross-references. Missing @param/@return tags
added on undocumented public methods.
Documentation-only; no production code or signatures changed.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Closes #24158
---
.../camel/spi/AutoMockInterceptStrategy.java | 12 ++++----
.../org/apache/camel/spi/BootstrapCloseable.java | 7 +++--
.../apache/camel/spi/CamelContextCustomizer.java | 14 ++++++++-
.../apache/camel/spi/CamelContextNameStrategy.java | 7 ++++-
.../org/apache/camel/spi/CamelContextTracker.java | 29 ++++++++++++++++++-
.../org/apache/camel/spi/ComponentCustomizer.java | 15 +++++++++-
.../apache/camel/spi/ContextReloadStrategy.java | 12 +++++---
.../main/java/org/apache/camel/spi/Contract.java | 33 +++++++++++++++++++++-
.../org/apache/camel/spi/DataFormatCustomizer.java | 15 +++++++++-
.../main/java/org/apache/camel/spi/DataType.java | 2 ++
.../org/apache/camel/spi/DataTypeTransformer.java | 13 +++++++--
.../main/java/org/apache/camel/spi/GroupAware.java | 7 ++++-
.../main/java/org/apache/camel/spi/HasGroup.java | 10 +++++--
.../src/main/java/org/apache/camel/spi/HasId.java | 9 ++++--
.../main/java/org/apache/camel/spi/IdAware.java | 10 ++++---
.../apache/camel/spi/InterceptEndpointFactory.java | 6 +++-
.../apache/camel/spi/InterceptSendToEndpoint.java | 10 +++++--
.../org/apache/camel/spi/InterceptStrategy.java | 18 ++++++++----
.../apache/camel/spi/InterceptableProcessor.java | 8 ++++--
.../org/apache/camel/spi/LanguageCustomizer.java | 15 +++++++++-
.../java/org/apache/camel/spi/ReloadStrategy.java | 9 +++++-
.../java/org/apache/camel/spi/RouteIdAware.java | 6 ++--
.../apache/camel/spi/StartupConditionStrategy.java | 9 ++++--
.../java/org/apache/camel/spi/StepIdAware.java | 6 ++--
24 files changed, 230 insertions(+), 52 deletions(-)
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/AutoMockInterceptStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/AutoMockInterceptStrategy.java
index c51c364b6b2b..4af05fd6a705 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/AutoMockInterceptStrategy.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/AutoMockInterceptStrategy.java
@@ -17,13 +17,11 @@
package org.apache.camel.spi;
/**
- * Strategy for intercepting sending messages to endpoints.
- *
- * The strategy can match by uri or pattern, and determine whether to skip
sending the message to the original intended
- * endpoints.
- *
- * This is used by camel-test for the auto mocking feature (such as
@MockEndpoint). See the
- * org.apache.camel.processor.AutoMockInterceptProducer.
+ * Strategy for intercepting messages sent to endpoints in order to auto-mock
them during testing.
+ * <p/>
+ * Matching by uri or uri pattern, the strategy can redirect sends to a mock
and optionally skip sending to the original
+ * endpoint. This powers the camel-test auto-mocking feature (such as {@code
@MockEndpoint}); see
+ * {@code org.apache.camel.processor.AutoMockInterceptProducer}.
*
* @since 4.15
*/
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/BootstrapCloseable.java
b/core/camel-api/src/main/java/org/apache/camel/spi/BootstrapCloseable.java
index fd2d92e30656..e77de16e271d 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/BootstrapCloseable.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/BootstrapCloseable.java
@@ -19,9 +19,10 @@ package org.apache.camel.spi;
import java.io.Closeable;
/**
- * A marker interface for a service, or other kind of process that is only
used during bootstrapping Camel. After the
- * bootstrap is complete the {@link #close()} method is invoked which allows
to do some cleanup processes such as
- * clearing internal caches, maps etc to clear up memory etc.
+ * Marker for a service (or other process) that is only needed while Camel is
bootstrapping.
+ * <p/>
+ * Once bootstrap completes, Camel invokes {@link #close()} so the
implementation can release bootstrap-only state, for
+ * example clearing internal caches and maps to free memory that is not needed
at runtime.
*
* @since 3.7
*/
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextCustomizer.java
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextCustomizer.java
index cba7a3ab3fa5..3367ea1d1bb2 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextCustomizer.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextCustomizer.java
@@ -20,8 +20,20 @@ import org.apache.camel.CamelContext;
import org.apache.camel.Ordered;
/**
- * To apply custom configurations to {@link CamelContext} instances.
+ * Strategy for applying custom configuration to a {@link CamelContext} after
it has been created.
+ * <p/>
+ * Customizers are discovered from the {@link Registry} and invoked during
bootstrap, giving a hook to programmatically
+ * tune the context (adding services, configuring options, registering beans)
without subclassing. Multiple customizers
+ * run in {@link Ordered} order. This is most commonly used by runtimes such
as Spring Boot and Quarkus to apply
+ * user-provided configuration. The sibling SPIs {@link ComponentCustomizer},
{@link DataFormatCustomizer}, and
+ * {@link LanguageCustomizer} customize individual components, data formats,
and languages.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/camelcontext-autoconfigure.html";>CamelContext
auto-configuration</a> in
+ * the Camel user manual.
*
+ * @see ComponentCustomizer
+ * @see DataFormatCustomizer
+ * @see LanguageCustomizer
* @since 3.6
*/
@FunctionalInterface
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextNameStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextNameStrategy.java
index d37b45a70bf2..baabe7992b50 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextNameStrategy.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextNameStrategy.java
@@ -17,7 +17,12 @@
package org.apache.camel.spi;
/**
- * Strategy for assigning name to a {@link org.apache.camel.CamelContext}.
+ * Strategy for assigning the name of a {@link org.apache.camel.CamelContext}.
+ * <p/>
+ * Camel uses the name strategy to determine the context's name, which appears
in logs, management (JMX), and tooling. A
+ * strategy may return a fixed name or compute a fresh one each time (for
example using a counter to keep names unique
+ * across multiple contexts in the same JVM); {@link #isFixedName()} reports
which. {@link ManagementNameStrategy} is
+ * the related strategy for the JMX management name.
*
* @see ManagementNameStrategy
*/
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextTracker.java
b/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextTracker.java
index 3a2ef3eac5fb..d7855ef71588 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextTracker.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/CamelContextTracker.java
@@ -29,7 +29,13 @@ import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
- * A {@link CamelContext} creation and destruction tracker.
+ * Tracks the creation and destruction of {@link CamelContext} instances
across the JVM.
+ * <p/>
+ * A tracker is activated by calling {@link #open()} (and deactivated via
{@link #close()}); while open it is notified
+ * through {@link #contextCreated(CamelContext)} and {@link
#contextDestroyed(CamelContext)} for every context that
+ * passes its {@link Filter} (by default, non-proxy contexts). Registration is
global and static, making this suited to
+ * cross-cutting concerns such as metrics or diagnostics that must observe all
contexts rather than a single
+ * {@link CamelContext}. Subclass and override the callbacks to react.
*/
public class CamelContextTracker implements Closeable {
@@ -39,9 +45,18 @@ public class CamelContextTracker implements Closeable {
private static final Lock LOCK = new ReentrantLock();
+ /**
+ * Decides which {@link CamelContext} instances a {@link
CamelContextTracker} is notified about.
+ */
@FunctionalInterface
public interface Filter extends Predicate<CamelContext> {
+ /**
+ * Whether the given context should be tracked.
+ *
+ * @param camelContext the camel context
+ * @return <tt>true</tt> to track the context
+ */
boolean accept(CamelContext camelContext);
@Override
@@ -98,6 +113,12 @@ public class CamelContextTracker implements Closeable {
TRACKERS.remove(this);
}
+ /**
+ * Notifies all open trackers that the given {@link CamelContext} has been
created. Called by Camel; exceptions from
+ * trackers are logged and ignored.
+ *
+ * @param camelContext the created camel context
+ */
public static void notifyContextCreated(CamelContext camelContext) {
Objects.requireNonNull(camelContext, "camelContext");
LOCK.lock();
@@ -116,6 +137,12 @@ public class CamelContextTracker implements Closeable {
}
}
+ /**
+ * Notifies all open trackers that the given {@link CamelContext} has been
destroyed. Called by Camel; exceptions
+ * from trackers are logged and ignored.
+ *
+ * @param camelContext the destroyed camel context
+ */
public static void notifyContextDestroyed(CamelContext camelContext) {
Objects.requireNonNull(camelContext, "camelContext");
LOCK.lock();
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ComponentCustomizer.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ComponentCustomizer.java
index a53d08f4701e..60b719591c85 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ComponentCustomizer.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ComponentCustomizer.java
@@ -26,7 +26,20 @@ import org.apache.camel.util.function.ThrowingConsumer;
import org.jspecify.annotations.Nullable;
/**
- * To apply custom configurations to {@link Component} instances.
+ * Strategy for applying custom configuration to {@link Component} instances
as they are created.
+ * <p/>
+ * Customizers are discovered from the {@link Registry} and applied to each
component during bootstrap, with
+ * {@link #isEnabled(String, Component)} (and an optional {@link Policy})
deciding whether a given component is
+ * customized, and {@link Ordered} controlling the order. Use the {@link
#builder()} /
+ * {@link #forType(Class, ThrowingConsumer)} helpers to target a concrete
component type. This is the component-level
+ * counterpart to {@link CamelContextCustomizer}.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/camelcontext-autoconfigure.html";>CamelContext
auto-configuration</a> in
+ * the Camel user manual.
+ *
+ * @see CamelContextCustomizer
+ * @see DataFormatCustomizer
+ * @see LanguageCustomizer
*/
@FunctionalInterface
public interface ComponentCustomizer extends Ordered {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ContextReloadStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ContextReloadStrategy.java
index c239b64f8a2e..fef53ef1db94 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/ContextReloadStrategy.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/ContextReloadStrategy.java
@@ -19,11 +19,15 @@ package org.apache.camel.spi;
import org.apache.camel.CamelContext;
/**
- * SPI strategy for reloading {@link CamelContext}.
- *
- * The reloading is limited to all routes and property placeholders. General
services in the {@link CamelContext} is not
- * reloaded.
+ * SPI strategy for reloading a running {@link CamelContext} in place.
+ * <p/>
+ * Reloading is limited to all routes and property placeholders; general
services in the {@link CamelContext} are not
+ * reloaded. This is the context-wide counterpart to {@link
ResourceReloadStrategy} (which reloads from changed
+ * resources) and builds on the generic {@link ReloadStrategy}.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/context-reload.html";>Context
Reload</a> in the Camel user manual.
*
+ * @see ReloadStrategy
* @see ResourceReloadStrategy
* @since 3.19
*/
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/Contract.java
b/core/camel-api/src/main/java/org/apache/camel/spi/Contract.java
index e5f7bb033ce3..f373c77c5a4b 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/Contract.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/Contract.java
@@ -23,7 +23,18 @@ import org.apache.camel.Processor;
import org.jspecify.annotations.Nullable;
/**
- * A Contract which represents the input type and/or output type of the {@link
Endpoint} or {@link Processor}.
+ * Declares the expected input and/or output {@link DataType} of an {@link
Endpoint} or {@link Processor}.
+ * <p/>
+ * When a route step declares a contract, Camel compares the message's actual
{@link DataType} against the declared
+ * input and output types and, if they differ, applies a matching {@link
Transformer} to convert the payload; it can
+ * also run a {@link Validator} when {@link #isValidateInput()} or {@link
#isValidateOutput()} is set. This is the
+ * mechanism behind declarative input/output typing on routes.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/transformer.html";>Transformer</a> in the
Camel user manual.
+ *
+ * @see DataType
+ * @see Transformer
+ * @see Validator
*/
public class Contract {
@@ -33,6 +44,11 @@ public class Contract {
private boolean validateOutput;
private @Nullable String contractString;
+ /**
+ * Gets the declared input data type.
+ *
+ * @return the input type, or <tt>null</tt> if none is declared
+ */
public @Nullable DataType getInputType() {
return inputType;
}
@@ -59,6 +75,11 @@ public class Contract {
this.contractString = null;
}
+ /**
+ * Gets the declared output data type.
+ *
+ * @return the output type, or <tt>null</tt> if none is declared
+ */
public @Nullable DataType getOutputType() {
return outputType;
}
@@ -85,6 +106,11 @@ public class Contract {
this.contractString = null;
}
+ /**
+ * Whether the input should be validated against the input data type.
+ *
+ * @return <tt>true</tt> if input validation is enabled
+ */
public boolean isValidateInput() {
return validateInput;
}
@@ -96,6 +122,11 @@ public class Contract {
this.validateInput = validate;
}
+ /**
+ * Whether the output should be validated against the output data type.
+ *
+ * @return <tt>true</tt> if output validation is enabled
+ */
public boolean isValidateOutput() {
return validateOutput;
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/DataFormatCustomizer.java
b/core/camel-api/src/main/java/org/apache/camel/spi/DataFormatCustomizer.java
index 4ee55e5aa3ec..49883fffa4d8 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/DataFormatCustomizer.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/DataFormatCustomizer.java
@@ -26,7 +26,20 @@ import org.apache.camel.util.function.ThrowingConsumer;
import org.jspecify.annotations.Nullable;
/**
- * To apply custom configurations to {@link DataFormat} instances.
+ * Strategy for applying custom configuration to {@link DataFormat} instances
as they are created.
+ * <p/>
+ * Customizers are discovered from the {@link Registry} and applied to each
data format during bootstrap, with
+ * {@link #isEnabled(String, DataFormat)} (and an optional {@link Policy})
deciding whether a given data format is
+ * customized, and {@link Ordered} controlling the order. Use the {@link
#builder()} /
+ * {@link #forType(Class, ThrowingConsumer)} helpers to target a concrete data
format type. This is the
+ * data-format-level counterpart to {@link CamelContextCustomizer}.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/camelcontext-autoconfigure.html";>CamelContext
auto-configuration</a> in
+ * the Camel user manual.
+ *
+ * @see CamelContextCustomizer
+ * @see ComponentCustomizer
+ * @see LanguageCustomizer
*/
@FunctionalInterface
public interface DataFormatCustomizer extends Ordered {
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/DataType.java
b/core/camel-api/src/main/java/org/apache/camel/spi/DataType.java
index aac9ad7e939f..07f083b154ba 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/DataType.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/DataType.java
@@ -37,6 +37,8 @@ import org.jspecify.annotations.Nullable;
* `http:cloud-events` and `aws-s3:cloud-events` where the scheme relates to
the respective component's scheme. This
* information could be leveraged to detect required {@link Transformer} and
{@link Validator} implementations provided
* as part of these components.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/transformer.html";>Transformer</a> in the
Camel user manual.
*
* @see DataTypeAware
* @see Transformer
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/DataTypeTransformer.java
b/core/camel-api/src/main/java/org/apache/camel/spi/DataTypeTransformer.java
index 0248fbb21435..3ea4a2068c3c 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/DataTypeTransformer.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/DataTypeTransformer.java
@@ -25,11 +25,18 @@ import java.lang.annotation.Target;
import org.apache.camel.spi.annotations.ServiceFactory;
/**
- * Annotation to configure a data type transformer with either specifying its
name or from/to data types.
+ * Marks a {@link Transformer} implementation as a data type transformer,
identified by its name and/or its from/to
+ * {@link DataType}s.
* <p/>
- * The annotation is used by specific classpath scanning data type loaders to
automatically add the data types to a
- * registry.
+ * Classpath-scanning transformer loaders discover annotated classes and
register them in the
+ * {@link TransformerRegistry}, so they can be detected and applied when a
route declares input/output data types via a
+ * {@link Contract}. Provide a unique {@link #name()}, or a {@link
#fromType()}/{@link #toType()} pair, so the
+ * transformer can be referenced or auto-detected.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/transformer.html";>Transformer</a> in the
Camel user manual.
*
+ * @see Transformer
+ * @see TransformerRegistry
* @since 4.0
*/
@Retention(RetentionPolicy.RUNTIME)
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/GroupAware.java
b/core/camel-api/src/main/java/org/apache/camel/spi/GroupAware.java
index 1d8fc9c90832..727e3f80dbcd 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/GroupAware.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/GroupAware.java
@@ -19,7 +19,12 @@ package org.apache.camel.spi;
import org.jspecify.annotations.Nullable;
/**
- * To allow objects to be injected with an group.
+ * Marker for an object whose group can be injected.
+ * <p/>
+ * Extends {@link HasGroup} to add the ability to set the group an object
belongs to (used for clustering, JMX, and
+ * similar group-based operations).
+ *
+ * @see HasGroup
*/
public interface GroupAware extends HasGroup {
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/HasGroup.java
b/core/camel-api/src/main/java/org/apache/camel/spi/HasGroup.java
index 58cb623ab02a..ae28256df1e5 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/HasGroup.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/HasGroup.java
@@ -19,8 +19,14 @@ package org.apache.camel.spi;
import org.jspecify.annotations.Nullable;
/**
- * A simple marker interface for an object which has belongs to a group Group
which is useful for group related
- * operation such as clustering, JMX style API
+ * Marker for an object that belongs to a named group, useful for
group-related operations such as clustering and JMX
+ * APIs.
+ * <p/>
+ * Grouping lets related objects be addressed or managed together. {@link
GroupAware} extends this to also allow the
+ * group to be set.
+ *
+ * @see GroupAware
+ * @see HasId
*/
public interface HasGroup {
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/HasId.java
b/core/camel-api/src/main/java/org/apache/camel/spi/HasId.java
index 3fe8e6176aeb..c89b6550a07b 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/HasId.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/HasId.java
@@ -17,8 +17,13 @@
package org.apache.camel.spi;
/**
- * A simple marker interface for an object which has a unique ID which is
useful for referring to objects in REST or JMX
- * style APIs
+ * Marker for an object that exposes a unique id, useful for referencing it in
REST, JMX, and tooling APIs.
+ * <p/>
+ * Many Camel runtime objects (routes, processors, services) carry an id so
they can be looked up, managed, and
+ * correlated back to their model definition. {@link IdAware} extends this to
also allow the id to be set.
+ *
+ * @see IdAware
+ * @see HasGroup
*/
public interface HasId {
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/IdAware.java
b/core/camel-api/src/main/java/org/apache/camel/spi/IdAware.java
index 568a23be14f9..e20cb3f19c3b 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/IdAware.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/IdAware.java
@@ -17,11 +17,13 @@
package org.apache.camel.spi;
/**
- * To allow objects to be injected with an id, such as EIP {@link
org.apache.camel.Processor}s which has been defined
- * from Camel routes.
+ * Marker for an object whose id can be injected, such as EIP {@link
org.apache.camel.Processor}s created from Camel
+ * routes.
* <p/>
- * This allows access to the id of the processor at runtime, which makes it
easier to map it to the corresponding model
- * definition.
+ * Camel assigns the id (explicit or auto-generated) so it is available at
runtime, which makes it easier to map the
+ * object back to its corresponding model definition. Extends {@link HasId} to
add the ability to set the id.
+ *
+ * @see HasId
*/
public interface IdAware extends HasId {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/InterceptEndpointFactory.java
b/core/camel-api/src/main/java/org/apache/camel/spi/InterceptEndpointFactory.java
index 7ff7eca06c2e..bfe5c8430531 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/InterceptEndpointFactory.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/InterceptEndpointFactory.java
@@ -23,8 +23,12 @@ import org.apache.camel.Processor;
import org.jspecify.annotations.Nullable;
/**
- * A factory to create {@link Endpoint} which are intercepted.
+ * Factory for creating an {@link InterceptSendToEndpoint} that intercepts
messages sent to an {@link Endpoint}.
+ * <p/>
+ * This backs the interceptSendToEndpoint EIP: the created endpoint detours
the exchange through optional before/after
+ * processors and may skip sending to the original endpoint. Used internally
when a route configures send interception.
*
+ * @see InterceptSendToEndpoint
* @since 3.7
*/
public interface InterceptEndpointFactory {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/InterceptSendToEndpoint.java
b/core/camel-api/src/main/java/org/apache/camel/spi/InterceptSendToEndpoint.java
index b8badf4fb22b..4a8aa573b259 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/InterceptSendToEndpoint.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/InterceptSendToEndpoint.java
@@ -22,8 +22,14 @@ import org.apache.camel.Processor;
import org.jspecify.annotations.Nullable;
/**
- * This is an endpoint when sending to it, is intercepted and is routed in a
detour, with the following flow: before,
- * send to original endpoint (can be skipped), after (optional).
+ * An {@link Endpoint} wrapper that, when sent to, detours the exchange:
before, send to the original endpoint (which
+ * can be skipped), then after (optional).
+ * <p/>
+ * This is the endpoint created by {@link InterceptEndpointFactory} to
implement the interceptSendToEndpoint EIP. The
+ * before/after {@link Processor}s and the optional {@link Predicate} guard
are configurable, as is whether the original
+ * send is {@link #isSkip() skipped}.
+ *
+ * @see InterceptEndpointFactory
*/
public interface InterceptSendToEndpoint extends Endpoint {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/InterceptStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/InterceptStrategy.java
index 6044968658bc..cfdedbb728e5 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/InterceptStrategy.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/InterceptStrategy.java
@@ -22,15 +22,21 @@ import org.apache.camel.Processor;
import org.jspecify.annotations.Nullable;
/**
- * The purpose of this interface is to allow an implementation to wrap
processors in a route with interceptors. For
- * example, a possible usecase is to gather performance statistics at the
processor's level.
+ * Strategy that wraps the {@link Processor}s in a route with interceptors,
for cross-cutting concerns such as gathering
+ * performance statistics at the processor level.
* <p/>
- * Its <b>strongly</b> adviced to use an {@link
org.apache.camel.AsyncProcessor} as the returned wrapped
- * {@link Processor} which ensures the interceptor works well with the
asynchronous routing engine. You can use the
+ * Camel invokes {@link #wrapProcessorInInterceptors} for each processor while
building a route, giving the strategy the
+ * chance to return a wrapping processor (or the original). Registered
strategies are applied to every interceptable
+ * processor; a processor can opt out by implementing {@link
InterceptableProcessor}.
+ * <p/>
+ * It is <b>strongly</b> advised to return an {@link
org.apache.camel.AsyncProcessor} as the wrapper, which ensures the
+ * interceptor works well with the asynchronous routing engine. You can use
* {@link org.apache.camel.support.processor.DelegateAsyncProcessor} to easily
return an
- * {@link org.apache.camel.AsyncProcessor} and override the
+ * {@link org.apache.camel.AsyncProcessor} and override
* {@link org.apache.camel.AsyncProcessor#process(org.apache.camel.Exchange,
org.apache.camel.AsyncCallback)} to
- * implement your interceptor logic. And just invoke the super method to
<b>continue</b> routing.
+ * implement your interceptor logic, then invoke the super method to
<b>continue</b> routing.
+ *
+ * @see InterceptableProcessor
*/
public interface InterceptStrategy {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/InterceptableProcessor.java
b/core/camel-api/src/main/java/org/apache/camel/spi/InterceptableProcessor.java
index 123568712783..79aa236f1c83 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/InterceptableProcessor.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/InterceptableProcessor.java
@@ -19,10 +19,12 @@ package org.apache.camel.spi;
import org.apache.camel.Processor;
/**
- * To control whether a {@link Processor} can be intercepted via {@link
InterceptStrategy}.
- *
- * Some EIPs such as try/catch/finally cannot be intercepted.
+ * Implemented by a {@link Processor} to control whether it may be wrapped by
an {@link InterceptStrategy}.
+ * <p/>
+ * Most processors are interceptable, but some EIPs (such as
try/catch/finally) cannot be intercepted safely;
+ * {@link #canIntercept()} returns {@code false} for those so Camel skips
wrapping them.
*
+ * @see InterceptStrategy
* @since 4.7
*/
public interface InterceptableProcessor {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/LanguageCustomizer.java
b/core/camel-api/src/main/java/org/apache/camel/spi/LanguageCustomizer.java
index 33953efe2cce..16f52e8ba44d 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/LanguageCustomizer.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/LanguageCustomizer.java
@@ -26,7 +26,20 @@ import org.apache.camel.util.function.ThrowingConsumer;
import org.jspecify.annotations.Nullable;
/**
- * To apply custom configurations to {@link Language} instances.
+ * Strategy for applying custom configuration to {@link Language} instances as
they are created.
+ * <p/>
+ * Customizers are discovered from the {@link Registry} and applied to each
language during bootstrap, with
+ * {@link #isEnabled(String, Language)} (and an optional {@link Policy})
deciding whether a given language is
+ * customized, and {@link Ordered} controlling the order. Use the {@link
#builder()} /
+ * {@link #forType(Class, ThrowingConsumer)} helpers to target a concrete
language type. This is the language-level
+ * counterpart to {@link CamelContextCustomizer}.
+ * <p/>
+ * See <a
href="https://camel.apache.org/manual/camelcontext-autoconfigure.html";>CamelContext
auto-configuration</a> in
+ * the Camel user manual.
+ *
+ * @see CamelContextCustomizer
+ * @see ComponentCustomizer
+ * @see DataFormatCustomizer
*/
@FunctionalInterface
public interface LanguageCustomizer extends Ordered {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ReloadStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ReloadStrategy.java
index 2891c74a18ca..778f301ae2f7 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ReloadStrategy.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ReloadStrategy.java
@@ -21,7 +21,14 @@ import org.apache.camel.StaticService;
import org.jspecify.annotations.Nullable;
/**
- * SPI strategy for reloading.
+ * SPI strategy for reloading Camel at runtime when a change is detected.
+ * <p/>
+ * A reload is triggered via {@link #onReload(Object)}, and the strategy
tracks success and failure counts
+ * ({@link #getReloadCounter()}, {@link #getFailedCounter()}) and the {@link
#getLastError() last error}. Concrete
+ * strategies target different scopes: {@link ContextReloadStrategy} reloads
routes and property placeholders in the
+ * running context, while {@link ResourceReloadStrategy} reloads from changed
{@link Resource}s.
+ * <p/>
+ * See <a href="https://camel.apache.org/manual/context-reload.html";>Context
Reload</a> in the Camel user manual.
*
* @see ContextReloadStrategy
* @see ResourceReloadStrategy
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/RouteIdAware.java
b/core/camel-api/src/main/java/org/apache/camel/spi/RouteIdAware.java
index 6175e2eeb2f5..ec6314e4a844 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/RouteIdAware.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/RouteIdAware.java
@@ -19,10 +19,12 @@ package org.apache.camel.spi;
import org.jspecify.annotations.Nullable;
/**
- * To allow objects to be injected with the route id
+ * Marker for an object whose owning route id can be injected.
* <p/>
- * This allows access to the route id of the processor at runtime, to know
which route its associated with.
+ * This gives access to the route id at runtime, so a processor or service
knows which route it is associated with (for
+ * example for logging, management, or tracing).
*
+ * @see IdAware
* @since 3.1
*/
public interface RouteIdAware {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/StartupConditionStrategy.java
b/core/camel-api/src/main/java/org/apache/camel/spi/StartupConditionStrategy.java
index 96220c6aca91..81355e85c561 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/StartupConditionStrategy.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/StartupConditionStrategy.java
@@ -21,8 +21,13 @@ import java.util.List;
import org.apache.camel.StaticService;
/**
- * Strategy for performing checks on startup that can validate whether Camel
can be started, or wait for some conditions
- * to be satisfied, before Camel can continue to startup.
+ * Strategy that runs {@link StartupCondition} checks during startup to decide
whether Camel may start, optionally
+ * waiting until the conditions are satisfied.
+ * <p/>
+ * Conditions are registered via {@link
#addStartupCondition(StartupCondition)} (or by class name) and evaluated by
+ * {@link #checkStartupConditions()}; the strategy polls at a configurable
{@link #getInterval() interval} up to a
+ * {@link #getTimeout() timeout}, and {@link #getOnTimeout() on timeout}
either fails, stops, or ignores. Useful to
+ * delay startup until an external dependency (database, broker, etc.) is
reachable.
*
* @see StartupCondition
* @since 4.9
diff --git a/core/camel-api/src/main/java/org/apache/camel/spi/StepIdAware.java
b/core/camel-api/src/main/java/org/apache/camel/spi/StepIdAware.java
index 17ca680fc667..ef67b807ed37 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/StepIdAware.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/StepIdAware.java
@@ -19,10 +19,12 @@ package org.apache.camel.spi;
import org.jspecify.annotations.Nullable;
/**
- * To allow objects to be injected with the step id
+ * Marker for an object whose owning step id can be injected.
* <p/>
- * This allows access to the step id at runtime, to know which step its
associated with.
+ * This gives access to the step id at runtime, so a processor knows which
step (the Step EIP) it is associated with.
*
+ * @see IdAware
+ * @see RouteIdAware
* @since 4.21
*/
public interface StepIdAware {
