CAMEL-23535: camel-api - batch 3: enhance class-level javadoc for endpoint/component/producer/consumer types

core/camel-api/src/main/java/org/apache/camel/ApiEndpoint.java

@@ -17,8 +17,14 @@
 package org.apache.camel;
 
 /**
- * Marks the {@link Endpoint} as an endpoint from an API based component.
+ * Marker interface indicating that an {@link Endpoint} belongs to an API-based component, where the endpoint URI
+ * encodes an API name and method name rather than a plain scheme and path.
+ * <p/>
+ * API-based components (for example camel-box) are typically generated from an API specification and expose many
+ * operations as distinct endpoint URIs. This interface allows tooling and the Camel catalog to identify and document
+ * them as API endpoints.
  *
+ * @see   Endpoint
  * @since 3.6
  */
 public interface ApiEndpoint extends Endpoint {

core/camel-api/src/main/java/org/apache/camel/AsyncCallback.java

@@ -22,6 +22,8 @@
  * For example a {@link AsyncProcessor} should invoke the done method when the {@link Exchange} is ready to be continued
  * routed. This allows to implement asynchronous {@link Producer} which can continue routing {@link Exchange} when all
  * the data has been gathered. This allows to build non blocking request/reply communication.
+ *
+ * @see AsyncProcessor
  */
 public interface AsyncCallback extends Runnable {
 

core/camel-api/src/main/java/org/apache/camel/AsyncEndpoint.java

@@ -17,7 +17,16 @@
 package org.apache.camel;
 
 /**
- * Marks the {@link Endpoint} as support asynchronous non-blocking routing in its consumer and producer.
+ * Marker interface indicating that the {@link Endpoint}'s consumer and producer support asynchronous, non-blocking
+ * routing.
+ * <p/>
+ * When an endpoint implements this interface, the Camel routing engine can pass an {@link AsyncCallback} to the
+ * producer's {@link AsyncProcessor#process(Exchange, AsyncCallback)} method instead of blocking until the exchange
+ * completes.
+ *
+ * @see Endpoint
+ * @see AsyncProcessor
+ * @see AsyncProducer
  */
 public interface AsyncEndpoint extends Endpoint {
 

core/camel-api/src/main/java/org/apache/camel/AsyncProcessor.java

@@ -24,6 +24,9 @@
  * <p/>
  * Any processor can be coerced to have an {@link AsyncProcessor} interface by using the
  * {@link org.apache.camel.support.AsyncProcessorConverterHelper#convert AsyncProcessorConverterHelper.convert} method.
+ *
+ * @see Processor
+ * @see AsyncCallback
  */
 public interface AsyncProcessor extends Processor {
 

core/camel-api/src/main/java/org/apache/camel/AsyncProducer.java

@@ -17,7 +17,14 @@
 package org.apache.camel;
 
 /**
- * Asynchronous producer
+ * A {@link Producer} that can dispatch an {@link Exchange} to an {@link Endpoint} without blocking the calling thread.
+ * <p/>
+ * Implementations override {@link AsyncProcessor#process(Exchange, AsyncCallback)} to complete the dispatch without
+ * blocking and invoke the {@link AsyncCallback} when processing is done.
+ *
+ * @see Producer
+ * @see AsyncProcessor
+ * @see AsyncCallback
  */
 public interface AsyncProducer extends Producer, AsyncProcessor {
 

core/camel-api/src/main/java/org/apache/camel/BatchConsumer.java

@@ -19,7 +19,16 @@
 import java.util.Queue;
 
 /**
- * A consumer of a batch of message exchanges from an {@link Endpoint}
+ * A {@link Consumer} that receives messages from an {@link Endpoint} in discrete batches rather than one at a time.
+ * <p/>
+ * Batch consumers expose a {@link #setMaxMessagesPerPoll(int)} limit to bound the number of messages fetched in a
+ * single polling cycle, which helps control memory usage and startup latency.
+ * <p/>
+ * During graceful shutdown, the {@link ShutdownRunningTask} option controls whether a batch in progress is completed in
+ * full or interrupted after the current message.
+ *
+ * @see Consumer
+ * @see ShutdownRunningTask
  */
 public interface BatchConsumer extends Consumer {
 

core/camel-api/src/main/java/org/apache/camel/Channel.java

@@ -26,6 +26,9 @@
  * Channel acts as a channel between {@link Processor}s in the route graph.
  * <p/>
  * The channel is responsible for routing the {@link Exchange} to the next {@link Processor} in the route graph.
+ *
+ * @see Processor
+ * @see Route
  */
 public interface Channel extends AsyncProcessor, Navigate<Processor> {
 

core/camel-api/src/main/java/org/apache/camel/Component.java

@@ -27,6 +27,15 @@
 
 /**
  * A <a href="https://camel.apache.org/component.html">component</a> is a factory of {@link Endpoint} objects.
+ * <p/>
+ * A component is registered in the {@link CamelContext} under a URI scheme (for example {@code "kafka"} or
+ * {@code "file"}) and is responsible for creating {@link Endpoint} instances for URIs that match that scheme.
+ * <p/>
+ * Components participate in the Camel lifecycle as {@link Service}s: they are started before any of their endpoints and
+ * stopped after the last endpoint is stopped.
+ *
+ * @see Endpoint
+ * @see CamelContext
  */
 public interface Component extends CamelContextAware, Service {
 

core/camel-api/src/main/java/org/apache/camel/ComponentAware.java

@@ -19,7 +19,11 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * An interface to represent an object which wishes to be injected with a {@link Component}.
+ * Implemented by objects, such as {@link Endpoint}, that are associated with and can expose their parent
+ * {@link Component}.
+ *
+ * @see Component
+ * @see Endpoint
  */
 public interface ComponentAware {
 

core/camel-api/src/main/java/org/apache/camel/Consumer.java

@@ -20,11 +20,21 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * A consumer of message exchanges from an {@link Endpoint}.
+ * A service that receives messages from an {@link Endpoint} and routes them as {@link Exchange}s through the Camel
+ * processing pipeline.
+ * <p/>
+ * Consumers are created by calling {@link Endpoint#createConsumer(Processor)} and participate in the Camel lifecycle as
+ * {@link Service}s. For endpoints that require a dedicated polling loop, see {@link PollingConsumer}; for endpoints
+ * that deliver messages in batches, see {@link BatchConsumer}.
  * <p/>
  * Important: Do not do any initialization in the constructor. Instead use
  * {@link org.apache.camel.support.service.ServiceSupport#doInit()} or
  * {@link org.apache.camel.support.service.ServiceSupport#doStart()}.
+ *
+ * @see Producer
+ * @see PollingConsumer
+ * @see BatchConsumer
+ * @see Endpoint
  */
 public interface Consumer extends Service, EndpointAware {
 

core/camel-api/src/main/java/org/apache/camel/DelegateEndpoint.java

@@ -17,7 +17,13 @@
 package org.apache.camel;
 
 /**
- * An interface to represent an {@link org.apache.camel.Endpoint} which are delegated.
+ * An {@link Endpoint} that delegates all operations to another underlying {@link Endpoint}, following the
+ * <em>Decorator</em> pattern.
+ * <p/>
+ * Implementations use this interface to wrap an existing endpoint to modify, intercept, or enrich its behaviour without
+ * changing the endpoint URI visible to the rest of the routing engine.
+ *
+ * @see Endpoint
  */
 public interface DelegateEndpoint extends Endpoint {
 

core/camel-api/src/main/java/org/apache/camel/DelegateProcessor.java

@@ -19,7 +19,13 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Interface to be used for processors that delegate to the real processor
+ * A {@link Processor} that wraps another {@link Processor} and delegates {@link Exchange} processing to it, following
+ * the <em>Decorator</em> pattern.
+ * <p/>
+ * Implementations use this interface to intercept, modify, or enrich exchanges before and after they are forwarded to
+ * the delegate processor.
+ *
+ * @see Processor
  */
 public interface DelegateProcessor extends Processor {
 

core/camel-api/src/main/java/org/apache/camel/DynamicPollingConsumer.java

@@ -19,9 +19,14 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * A {@link PollingConsumer} that are used by dynamic Poll and PollEnrich EIPs to facilitate components that can use
- * information from the current {@link Exchange} during the poll.
+ * A {@link PollingConsumer} used by the dynamic {@code poll} and {@code pollEnrich} EIPs, allowing the component to use
+ * data from the current {@link Exchange} (such as headers or properties) to parameterise the poll operation at runtime.
+ * <p/>
+ * Components that support dynamic polling implement this interface in addition to {@link PollingConsumer} to provide
+ * exchange-aware overloads of the three receive methods.
  *
+ * @see   PollingConsumer
+ * @see   Exchange
  * @since 4.11
  */
 public interface DynamicPollingConsumer extends PollingConsumer {

core/camel-api/src/main/java/org/apache/camel/Endpoint.java

@@ -28,6 +28,9 @@
  *
  * @see Exchange
  * @see Message
+ * @see Component
+ * @see Producer
+ * @see Consumer
  */
 public interface Endpoint extends IsSingleton, Service, ComponentAware {
 

core/camel-api/src/main/java/org/apache/camel/EndpointAware.java

@@ -17,7 +17,12 @@
 package org.apache.camel;
 
 /**
- * An interface to represent an object such as a {@link org.apache.camel.Processor} that uses an {@link Endpoint}
+ * Implemented by objects that are associated with a specific {@link Endpoint}, such as a {@link Producer} sending to an
+ * endpoint or a {@link Consumer} reading from one.
+ *
+ * @see Endpoint
+ * @see Producer
+ * @see Consumer
  */
 public interface EndpointAware {
 

core/camel-api/src/main/java/org/apache/camel/FailedToCreateRouteFromTemplateException.java

@@ -19,8 +19,12 @@
 import java.util.Objects;
 
 /**
- * Exception when failing to create a {@link Route} from a RouteTemplateDefinition.
+ * Thrown when the {@link CamelContext} fails to instantiate a {@link Route} from a route template definition, for
+ * example because a required template parameter is missing or the generated route is invalid.
+ * <p/>
+ * Carries the template id and the target route id to help diagnose which template and instantiation attempt failed.
  *
+ * @see   Route
  * @since 3.10
  */
 public class FailedToCreateRouteFromTemplateException extends RuntimeCamelException {

core/camel-api/src/main/java/org/apache/camel/MultipleConsumersSupport.java

@@ -27,6 +27,9 @@
  * <p/>
  * The purpose of this is to check on startup that we do not have multiple consumers for the <b>same</b> endpoints. This
  * prevents starting up with copy/paste mistakes in the Camel routes.
+ *
+ * @see Endpoint
+ * @see Consumer
  */
 public interface MultipleConsumersSupport {
 

core/camel-api/src/main/java/org/apache/camel/NoSuchEndpointException.java

@@ -21,8 +21,14 @@
 import static org.apache.camel.util.URISupport.sanitizeUri;
 
 /**
- * A runtime exception thrown if a routing processor such as a recipient list is unable to resolve an {@link Endpoint}
- * from a URI.
+ * Thrown when a routing processor (such as a recipient list or dynamic router) cannot resolve a URI to a known
+ * {@link Endpoint}, typically because the required Camel component is missing from the classpath.
+ * <p/>
+ * Contrast with {@link ResolveEndpointFailedException}, which is thrown when the component is present but the URI is
+ * malformed or configuration fails.
+ *
+ * @see ResolveEndpointFailedException
+ * @see Endpoint
  */
 public class NoSuchEndpointException extends RuntimeCamelException {
 

core/camel-api/src/main/java/org/apache/camel/PollingConsumer.java

@@ -31,6 +31,9 @@
  * Important: Do not do any initialization in the constructor. Instead use
  * {@link org.apache.camel.support.service.ServiceSupport#doInit()} or
  * {@link org.apache.camel.support.service.ServiceSupport#doStart()}.
+ *
+ * @see DynamicPollingConsumer
+ * @see BatchConsumer
  */
 public interface PollingConsumer extends Consumer {
 

core/camel-api/src/main/java/org/apache/camel/Processor.java

@@ -25,6 +25,9 @@
  * Notice if you use a {@link Processor} in a Camel route, then make sure to write the {@link Processor} in a
  * thread-safe way, as the Camel routes can potentially be executed by concurrent threads, and therefore multiple
  * threads can call the same {@link Processor} instance.
+ *
+ * @see AsyncProcessor
+ * @see Exchange
  */
 @FunctionalInterface
 public interface Processor {

core/camel-api/src/main/java/org/apache/camel/Producer.java

@@ -17,11 +17,19 @@
 package org.apache.camel;
 
 /**
- * Provides a channel on which clients can create and invoke message exchanges on an {@link Endpoint}.
+ * A service that sends {@link Exchange}s to an {@link Endpoint}.
+ * <p/>
+ * A producer is created by calling {@link Endpoint#createProducer()} and participates in the Camel lifecycle as a
+ * {@link Service}. Calls to {@link #process(Exchange)} block until processing of the exchange completes; for
+ * non-blocking dispatch use {@link AsyncProducer}.
  * <p/>
  * Important: Do not do any initialization in the constructor. Instead use
  * {@link org.apache.camel.support.service.ServiceSupport#doInit()} or
  * {@link org.apache.camel.support.service.ServiceSupport#doStart()}.
+ *
+ * @see Consumer
+ * @see AsyncProducer
+ * @see Endpoint
  */
 public interface Producer extends Processor, Service, IsSingleton, EndpointAware {
 

core/camel-api/src/main/java/org/apache/camel/ResolveEndpointFailedException.java

@@ -23,7 +23,13 @@
 import static org.apache.camel.util.URISupport.sanitizeUri;
 
 /**
- * A runtime exception thrown if an {@link Endpoint} cannot be resolved via URI
+ * Thrown when the {@link CamelContext} fails to resolve a URI to an {@link Endpoint}, for example because the scheme is
+ * unknown, the component is not on the classpath, or the URI contains invalid parameters.
+ * <p/>
+ * The reported URI is sanitized (credentials are masked) before being included in the exception message.
+ *
+ * @see Endpoint
+ * @see NoSuchEndpointException
  */
 public class ResolveEndpointFailedException extends RuntimeCamelException {
 

core/camel-api/src/main/java/org/apache/camel/ShutdownRoute.java

@@ -32,6 +32,8 @@
  * <li>Defer - Will defer shutting down the route and let it be active during graceful shutdown. The route will be
  * shutdown at a later stage during the graceful shutdown process.</li>
  * </ul>
+ *
+ * @see ShutdownRunningTask
  */
 @XmlType
 @XmlEnum

core/camel-api/src/main/java/org/apache/camel/ShutdownRunningTask.java

@@ -32,6 +32,9 @@
  * </ul>
  * <b>Notice:</b> Most consumers only have a single task, but {@link org.apache.camel.BatchConsumer} can have many tasks
  * and thus this option mostly applies to this kind of consumer.
+ *
+ * @see ShutdownRoute
+ * @see BatchConsumer
  */
 @XmlType
 @XmlEnum