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 7f1ba4cd05b7 CAMEL-23535: camel-api - batch 7: enhance class-level
Javadoc for type conversion and class resolution SPIs
7f1ba4cd05b7 is described below
commit 7f1ba4cd05b786bc8108266157901eee761edd09
Author: Adriano Machado <[email protected]>
AuthorDate: Sun Jun 7 15:24:19 2026 -0400
CAMEL-23535: camel-api - batch 7: enhance class-level Javadoc for type
conversion and class resolution SPIs
Enhance class-level Javadoc for 11 type conversion and class resolution
interfaces in core/camel-api: TypeConverter, TypeConverterExists,
TypeConverters, TypeConverterRegistry, TypeConverterLoader,
BulkTypeConverters, ClassResolver, PackageScanClassResolver,
PackageScanFilter, FactoryFinder, and FactoryFinderResolver.
Adds architecture context, cross-references, user manual links, and
@see tags. Javadoc-only changes — no code or API signature modifications.
Closes #23821
---
.../main/java/org/apache/camel/TypeConverter.java | 21 +++++++++++++++++---
.../java/org/apache/camel/TypeConverterExists.java | 12 ++++++++++-
.../main/java/org/apache/camel/TypeConverters.java | 14 ++++++++++---
.../org/apache/camel/spi/BulkTypeConverters.java | 15 ++++++++++----
.../java/org/apache/camel/spi/ClassResolver.java | 15 ++++++++++++--
.../java/org/apache/camel/spi/FactoryFinder.java | 14 ++++++++++++-
.../apache/camel/spi/FactoryFinderResolver.java | 11 ++++++++++-
.../apache/camel/spi/PackageScanClassResolver.java | 12 ++++++++++-
.../org/apache/camel/spi/PackageScanFilter.java | 15 +++++++++++++-
.../org/apache/camel/spi/TypeConverterLoader.java | 13 +++++++++++-
.../apache/camel/spi/TypeConverterRegistry.java | 23 ++++++++++++++++++----
11 files changed, 143 insertions(+), 22 deletions(-)
diff --git a/core/camel-api/src/main/java/org/apache/camel/TypeConverter.java
b/core/camel-api/src/main/java/org/apache/camel/TypeConverter.java
index 59ed57d1d6c8..43a8f8489a19 100644
--- a/core/camel-api/src/main/java/org/apache/camel/TypeConverter.java
+++ b/core/camel-api/src/main/java/org/apache/camel/TypeConverter.java
@@ -19,9 +19,24 @@ package org.apache.camel;
import org.jspecify.annotations.Nullable;
/**
- * A pluggable strategy to be able to convert objects <a
href="https://camel.apache.org/type-converter.html";>to
- * different types</a> such as to and from String, InputStream/OutputStream,
Reader/Writer, Document, byte[], ByteBuffer
- * etc
+ * Pluggable strategy for converting objects to <a
href="https://camel.apache.org/manual/type-converter.html";>different
+ * types</a> such as String, InputStream/OutputStream, Reader/Writer,
Document, byte[], and ByteBuffer.
+ * <p/>
+ * Type converters are a central part of Camel's integration infrastructure.
Whenever Camel reads an {@link Exchange}
+ * body or header and needs it in a different Java type, it delegates to the
+ * {@link org.apache.camel.spi.TypeConverterRegistry} to find an appropriate
{@code TypeConverter}. Converters are
+ * discovered automatically at startup by scanning classpath resources for the
{@link Converter} annotation, or they can
+ * be registered programmatically via
+ * {@link org.apache.camel.spi.TypeConverterRegistry#addTypeConverter(Class,
Class, TypeConverter)}.
+ * <p/>
+ * There are three conversion variants: {@link #convertTo} (returns {@code
null} when the conversion is unavailable),
+ * {@link #mandatoryConvertTo} (throws {@link
NoTypeConversionAvailableException} when no converter is found), and
+ * {@link #tryConvertTo} (silently returns {@code null} without propagating
exceptions).
+ *
+ * @see org.apache.camel.spi.TypeConverterRegistry
+ * @see Converter
+ * @see TypeConversionException
+ * @see NoTypeConversionAvailableException
*/
public interface TypeConverter {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/TypeConverterExists.java
b/core/camel-api/src/main/java/org/apache/camel/TypeConverterExists.java
index 42679ffed7f7..6f39c9e3c824 100644
--- a/core/camel-api/src/main/java/org/apache/camel/TypeConverterExists.java
+++ b/core/camel-api/src/main/java/org/apache/camel/TypeConverterExists.java
@@ -19,7 +19,17 @@ package org.apache.camel;
import jakarta.xml.bind.annotation.XmlEnum;
/**
- * What to do if attempting to add a duplicate type converter
+ * Policy controlling what happens when a {@link
org.apache.camel.spi.TypeConverterRegistry} receives a request to
+ * register a <a
href="https://camel.apache.org/manual/type-converter.html";>type converter</a>
whose from-to type pair
+ * is already registered.
+ * <p/>
+ * This policy is set on the registry via
+ * {@link
org.apache.camel.spi.TypeConverterRegistry#setTypeConverterExists(TypeConverterExists)}
and determines whether
+ * a duplicate registration replaces the existing converter ({@link
#Override}), is silently discarded
+ * ({@link #Ignore}), or raises a hard failure ({@link #Fail}). The default
behavior is {@link #Ignore}.
+ *
+ * @see org.apache.camel.spi.TypeConverterRegistry
+ * @see TypeConverter
*/
@XmlEnum
public enum TypeConverterExists {
diff --git a/core/camel-api/src/main/java/org/apache/camel/TypeConverters.java
b/core/camel-api/src/main/java/org/apache/camel/TypeConverters.java
index 54f83beec380..102dd193e5a4 100644
--- a/core/camel-api/src/main/java/org/apache/camel/TypeConverters.java
+++ b/core/camel-api/src/main/java/org/apache/camel/TypeConverters.java
@@ -17,10 +17,18 @@
package org.apache.camel;
/**
- * A tagging interface to mark this class implements type converters using the
{@link Converter} annotations.
+ * Marker interface indicating that a class contains <a
href="https://camel.apache.org/manual/type-converter.html";>type
+ * converter</a> methods annotated with {@link Converter}.
* <p/>
- * This can be used to provide custom type converters that can be manually
added to the {@link CamelContext} using
- * {@link
org.apache.camel.spi.TypeConverterRegistry#addTypeConverters(Object)}.
+ * Implementing this interface allows custom converter classes to be
registered at runtime with
+ * {@link
org.apache.camel.spi.TypeConverterRegistry#addTypeConverters(Object)}, making
all {@link Converter}-annotated
+ * methods available as converters within the current {@link CamelContext}.
+ * <p/>
+ * At startup, Camel automatically scans the classpath for converter classes;
this interface provides a way to register
+ * additional converters programmatically without requiring a classpath scan.
+ *
+ * @see Converter
+ * @see org.apache.camel.spi.TypeConverterRegistry
*/
public interface TypeConverters {
}
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/BulkTypeConverters.java
b/core/camel-api/src/main/java/org/apache/camel/spi/BulkTypeConverters.java
index cef29d7642d4..ca5b26c74ae9 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/BulkTypeConverters.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/BulkTypeConverters.java
@@ -24,11 +24,18 @@ import org.apache.camel.TypeConverter;
import org.jspecify.annotations.Nullable;
/**
- * Bulk type converters that often comes out of the box with Apache Camel.
Camel does a build phase where the Camel
- * artifacts are scanned for {@link org.apache.camel.Converter}s and then
bulked together into a single source code
- * generated class. This class is then used at runtime as an optimized and
really fast way of using all those type
- * converters by the {@link TypeConverterRegistry}.
+ * A source-code-generated, compile-time-optimized bundle of {@link
TypeConverter} instances for use with the
+ * <a href="https://camel.apache.org/manual/type-converter.html";>type
conversion</a> infrastructure.
+ * <p/>
+ * During the Camel build phase, all classes annotated with {@link
org.apache.camel.Converter} in a module are collected
+ * and merged into a single generated class implementing this interface. At
runtime the {@link TypeConverterRegistry}
+ * registers each such bulk class once via {@link
TypeConverterRegistry#addBulkTypeConverters(BulkTypeConverters)},
+ * replacing the overhead of per-pair hash map lookups with a single
polymorphic dispatch through the generated
+ * {@link #convertTo(Class, Class, org.apache.camel.Exchange, Object)} method,
significantly reducing overhead for
+ * high-throughput routes.
*
+ * @see TypeConverterRegistry
+ * @see org.apache.camel.Converter
* @since 3.7
*/
public interface BulkTypeConverters extends Ordered, TypeConverter {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/ClassResolver.java
b/core/camel-api/src/main/java/org/apache/camel/spi/ClassResolver.java
index 8dae03544b2c..f34d93edc709 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/ClassResolver.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/ClassResolver.java
@@ -24,8 +24,19 @@ import java.util.Set;
import org.jspecify.annotations.Nullable;
/**
- * A class resolver for loading classes in a loosly coupled manner to cater
for different platforms such as standalone,
- * Spring Boot, Quarkus, JBang etc.
+ * Platform-neutral strategy for loading classes and classpath resources
across the different runtimes that Camel
+ * supports (standalone JVM, Spring Boot, Quarkus, OSGi, JBang, and others).
+ * <p/>
+ * A single {@link org.apache.camel.CamelContext} maintains one {@code
ClassResolver} instance. Instead of calling
+ * {@code Class.forName()} or {@code ClassLoader.getResourceAsStream()}
directly, all Camel internals delegate to this
+ * interface so that custom or container-aware class loaders can participate
in class resolution without changes to the
+ * framework. Additional class loaders can be plugged in at any time via
{@link #addClassLoader(ClassLoader)}.
+ * <p/>
+ * The interface exposes both optional-return ({@link #resolveClass(String)})
and throwing
+ * ({@link #resolveMandatoryClass(String)}) variants so that callers can
choose the appropriate error-handling strategy.
+ *
+ * @see PackageScanClassResolver
+ * @see org.apache.camel.CamelContext#getClassResolver()
*/
public interface ClassResolver {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/FactoryFinder.java
b/core/camel-api/src/main/java/org/apache/camel/spi/FactoryFinder.java
index 91af20a08a46..aef74996f242 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/FactoryFinder.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/FactoryFinder.java
@@ -19,7 +19,19 @@ package org.apache.camel.spi;
import java.util.Optional;
/**
- * Finder to find factories from the resource classpath, usually
<b>META-INF/services/org/apache/camel/</b>.
+ * Looks up and instantiates SPI factory classes declared in resource files on
the classpath, following the
+ * {@code META-INF/services/org/apache/camel/} service-file convention used
throughout Camel.
+ * <p/>
+ * Each service file contains the fully-qualified class name of a factory
implementation. Given a lookup key, the finder
+ * appends the key to {@link #getResourcePath()}, reads the file, loads the
named class via the {@link ClassResolver},
+ * and instantiates it. This mechanism lets components and modules ship their
implementations without explicit
+ * registration; Camel discovers them automatically at startup via this
discovery contract.
+ * <p/>
+ * {@link FactoryFinderResolver} creates and caches {@code FactoryFinder}
instances per resource path, so each distinct
+ * path has exactly one finder for the lifetime of the {@link
org.apache.camel.CamelContext}.
+ *
+ * @see FactoryFinderResolver
+ * @see ClassResolver
*/
public interface FactoryFinder {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/FactoryFinderResolver.java
b/core/camel-api/src/main/java/org/apache/camel/spi/FactoryFinderResolver.java
index c75ad6c20e1e..b1ac02c54746 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/FactoryFinderResolver.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/FactoryFinderResolver.java
@@ -17,7 +17,16 @@
package org.apache.camel.spi;
/**
- * Represents a resolver for {@link FactoryFinder}
+ * Factory for creating and caching {@link FactoryFinder} instances, each
scoped to a specific resource-path prefix on
+ * the classpath.
+ * <p/>
+ * The {@link org.apache.camel.CamelContext} holds one {@code
FactoryFinderResolver} and uses it to obtain finders for
+ * the standard {@link FactoryFinder#DEFAULT_PATH} as well as for
bootstrap-phase lookups that must complete before the
+ * context is fully started. Separating bootstrap and runtime finders allows
implementations to apply different caching
+ * or isolation strategies during the two lifecycle phases.
+ *
+ * @see FactoryFinder
+ * @see ClassResolver
*/
public interface FactoryFinderResolver {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/PackageScanClassResolver.java
b/core/camel-api/src/main/java/org/apache/camel/spi/PackageScanClassResolver.java
index 3caaa71ccf1f..5d5b624fd25a 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/PackageScanClassResolver.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/PackageScanClassResolver.java
@@ -22,9 +22,19 @@ import java.util.Set;
import org.apache.camel.StaticService;
/**
- * A resolver that can find classes based on package scanning.
+ * Classpath scanning strategy for discovering classes by annotation,
supertype, or custom predicate across one or more
+ * packages, used by Camel at startup to auto-detect components, type
converters, and other pluggable types.
+ * <p/>
+ * The resolver scans all registered {@link ClassLoader} instances for {@code
.class} files under the specified package
+ * names (including sub-packages). Results are internally cached; call {@link
#clearCache()} to invalidate the cache
+ * when the classpath changes at runtime (for example, in OSGi or
hot-deployment environments).
+ * <p/>
+ * Global filters added via {@link #addFilter(PackageScanFilter)} are applied
to every subsequent scan operation, which
+ * is useful for excluding test or internal classes from production discovery.
*
+ * @see PackageScanFilter
* @see PackageScanResourceResolver
+ * @see ClassResolver
*/
public interface PackageScanClassResolver extends StaticService {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/PackageScanFilter.java
b/core/camel-api/src/main/java/org/apache/camel/spi/PackageScanFilter.java
index bede37312da8..10ab04327622 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/PackageScanFilter.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/PackageScanFilter.java
@@ -17,7 +17,20 @@
package org.apache.camel.spi;
/**
- * Filter that can be used with the {@link
org.apache.camel.spi.PackageScanClassResolver} resolver.
+ * Predicate applied by {@link PackageScanClassResolver} during classpath
scanning to determine whether a discovered
+ * class should be included in the result set.
+ * <p/>
+ * Implementations receive each candidate class and return {@code true} to
include it or {@code false} to skip it.
+ * Because this is a {@link FunctionalInterface}, a filter can be expressed as
a lambda or method reference:
+ *
+ * <pre>
+ * resolver.findByFilter(cls ->
cls.isAnnotationPresent(MyAnnotation.class), "com.example");
+ * </pre>
+ *
+ * Global filters registered via {@link
PackageScanClassResolver#addFilter(PackageScanFilter)} apply to every subsequent
+ * scan; per-query filters passed to {@link
PackageScanClassResolver#findByFilter} apply only to that single call.
+ *
+ * @see PackageScanClassResolver
*/
@FunctionalInterface
public interface PackageScanFilter {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/TypeConverterLoader.java
b/core/camel-api/src/main/java/org/apache/camel/spi/TypeConverterLoader.java
index 2dce48e13a0f..e3876af6c7b5 100644
--- a/core/camel-api/src/main/java/org/apache/camel/spi/TypeConverterLoader.java
+++ b/core/camel-api/src/main/java/org/apache/camel/spi/TypeConverterLoader.java
@@ -19,7 +19,18 @@ package org.apache.camel.spi;
import org.apache.camel.TypeConverterLoaderException;
/**
- * A pluggable strategy to load type converters into a {@link
TypeConverterRegistry} from some kind of mechanism.
+ * Pluggable strategy for discovering and loading {@link TypeConverter}
instances into a {@link TypeConverterRegistry}
+ * during {@link org.apache.camel.CamelContext} startup.
+ * <p/>
+ * Camel ships a default implementation that reads converter class names from
+ * {@code META-INF/services/org/apache/camel/TypeConverter} resource files on
the classpath, a convention that component
+ * modules use to register their converters automatically without explicit
wiring. Additional loaders can be supplied to
+ * support alternative discovery mechanisms such as loading converters from a
Spring {@code ApplicationContext} or an
+ * OSGi service registry.
+ *
+ * @see TypeConverterRegistry
+ * @see TypeConverter
+ * @see org.apache.camel.Converter
*/
public interface TypeConverterLoader {
diff --git
a/core/camel-api/src/main/java/org/apache/camel/spi/TypeConverterRegistry.java
b/core/camel-api/src/main/java/org/apache/camel/spi/TypeConverterRegistry.java
index fa5f80c94cdd..887b197f08fb 100644
---
a/core/camel-api/src/main/java/org/apache/camel/spi/TypeConverterRegistry.java
+++
b/core/camel-api/src/main/java/org/apache/camel/spi/TypeConverterRegistry.java
@@ -28,11 +28,26 @@ import org.apache.camel.TypeConverterExists;
import org.jspecify.annotations.Nullable;
/**
- * Registry for type converters.
+ * Central registry for all {@link TypeConverter} instances available in a
+ * <a href="https://camel.apache.org/manual/type-converter.html";>Camel
type-conversion</a> context.
* <p/>
- * The utilization {@link Statistics} is by default disabled, as it has a
slight performance impact under very high
- * concurrent load. The statistics can be enabled using
- * {@link
org.apache.camel.CamelContext#setTypeConverterStatisticsEnabled(Boolean)}
(boolean)} method.
+ * At startup, Camel discovers and loads type converters from the classpath
via {@link TypeConverterLoader}
+ * implementations and from compile-time-generated bundles through {@link
BulkTypeConverters}. At runtime, components
+ * and routes look up a converter for a given from-to type pair via {@link
#lookup(Class, Class)}. Converters can also
+ * be added or removed programmatically at any time.
+ * <p/>
+ * When two converters claim the same from-to pair, the registry applies the
{@link TypeConverterExists} policy
+ * (default: {@link TypeConverterExists#Ignore}). The registry also supports
<em>fallback</em> converters consulted when
+ * no primary converter is found for a pair.
+ * <p/>
+ * Usage statistics (hit/miss/fail counters) are available via {@link
#getStatistics()} but are disabled by default due
+ * to overhead under high concurrent load. Enable them with
+ * {@link
org.apache.camel.CamelContext#setTypeConverterStatisticsEnabled(Boolean)}.
+ *
+ * @see TypeConverter
+ * @see TypeConverterLoader
+ * @see BulkTypeConverters
+ * @see TypeConverterExists
*/
public interface TypeConverterRegistry extends StaticService,
CamelContextAware {
