CAMEL-23535: camel-api - enhance class-level javadoc for lifecycle and context types

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

@@ -17,7 +17,11 @@
 package org.apache.camel;
 
 /**
- * Exception thrown in situations when a {@link Service} has already been stopped.
+ * Thrown when an operation is attempted on a {@link Service} that has already been stopped and therefore cannot service
+ * the call.
+ * <p/>
+ * Typically raised when a producer or template is invoked after the owning {@link CamelContext} (or its parent route)
+ * has been shut down.
  */
 public class AlreadyStoppedException extends RuntimeCamelException {
 

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

@@ -60,15 +60,22 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Interface used to represent the CamelContext used to configure routes and the policies to use during message
- * exchanges between endpoints.
+ * The <a href="https://camel.apache.org/manual/camelcontext.html">CamelContext</a> is the runtime container of an
+ * Apache Camel application: it owns the registries of {@link Component}s, {@link Endpoint}s, {@link Route}s,
+ * {@link org.apache.camel.spi.TypeConverter}s, {@link org.apache.camel.spi.Language}s, {@link DataFormat}s and the
+ * configuration that governs how {@link Exchange}s flow between them.
+ * <p/>
+ * A {@link CamelContext} is created once per application (or per deployment unit) by the chosen runtime (Main, Spring
+ * Boot or Quarkus). Routes are added to the context using a {@link RoutesBuilder}, and the context is then started to
+ * begin processing message exchanges.
  * <p/>
  * The CamelContext offers the following methods {@link CamelContextLifecycle} to control the lifecycle:
  * <ul>
  * <li>{@link #start()} - to start</li>
- * <li>{@link #stop()} - to shutdown (will stop all routes/components/endpoints etc and clear internal state/cache)</li>
- * <li>{@link #suspend()} - to pause routing messages</li>
- * <li>{@link #resume()} - to resume after a suspend</li>
+ * <li>{@link #stop()} - to shut down (will stop all routes/components/endpoints etc. and clear internal
+ * state/cache)</li>
+ * <li>{@link #suspend()} - to pause message routing message</li>
+ * <li>{@link #resume()} - to resume after a suspended execution</li>
  * </ul>
  * <p/>
  * <b>Notice:</b> {@link #stop()} and {@link #suspend()} will gracefully stop/suspend routes ensuring any messages in
@@ -83,6 +90,10 @@
  * <p/>
  * You can use the {@link CamelContext#getCamelContextExtension()} to obtain the extension point for the
  * {@link CamelContext}. This extension point exposes internal APIs via {@link ExtendedCamelContext}.
+ *
+ * @see CamelContextLifecycle
+ * @see ExtendedCamelContext
+ * @see RoutesBuilder
  */
 public interface CamelContext extends CamelContextLifecycle, RuntimeConfiguration {
 

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

@@ -19,7 +19,17 @@
 import org.apache.camel.spi.HasCamelContext;
 
 /**
- * An interface to represent an object which wishes to be injected with the {@link CamelContext}
+ * Marker for objects that wish to receive the owning {@link CamelContext}.
+ * <p/>
+ * Camel inspects objects added to the context (components, processors, beans registered in the
+ * {@link org.apache.camel.spi.Registry}, route policies, ...) and, when they implement this interface,
+ * {@link #setCamelContext(CamelContext)} is called so they can keep a reference to their context. This is the standard
+ * way for SPI implementations and user beans to reach into Camel APIs from inside a route.
+ * <p/>
+ * The static {@link #trySetCamelContext(Object, CamelContext)} helper is convenient for code paths that wire up
+ * arbitrary objects without first knowing whether they need the context.
+ *
+ * @see CamelContext
  */
 public interface CamelContextAware extends HasCamelContext {
 

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

@@ -17,8 +17,17 @@
 package org.apache.camel;
 
 /**
- * Lifecycle API for {@link CamelContext}.
+ * Lifecycle API for {@link CamelContext}: the methods used to start, stop, suspend and resume a Camel runtime.
+ * <p/>
+ * Extracted from {@link CamelContext} so the lifecycle surface can be referenced independently of the rest of the
+ * context configuration API. See <a href="https://camel.apache.org/manual/lifecycle.html">Camel lifecycle</a> for the
+ * full description of states and transitions.
+ * <p/>
+ * As an {@link AutoCloseable}, a {@link CamelContext} can be used with try-with-resources to ensure {@link #close()} is
+ * invoked on exit.
  *
+ * @see   CamelContext
+ * @see   ServiceStatus
  * @since 3.2
  */
 public interface CamelContextLifecycle extends AutoCloseable {
@@ -27,7 +36,7 @@ public interface CamelContextLifecycle extends AutoCloseable {
      * Starts the {@link CamelContext} (<b>important:</b> the start method is not blocked, see more details in the
      * {@link Main} documentation for running Camel Standalone).
      * <p/>
-     * See more details at the class-level javadoc at {@link CamelContext}.
+     * See more details at the class-level Javadoc at {@link CamelContext}.
      *
      * @throws RuntimeCamelException is thrown if starting failed
      */
@@ -37,7 +46,7 @@ public interface CamelContextLifecycle extends AutoCloseable {
      * Stop and shutdown the {@link CamelContext} (will stop all routes/components/endpoints etc and clear internal
      * state/cache).
      * <p/>
-     * See more details at the class-level javadoc at {@link CamelContext}.
+     * See more details at the class-level Javadoc at {@link CamelContext}.
      *
      * @throws RuntimeCamelException is thrown if stopping failed
      */
@@ -95,7 +104,7 @@ public interface CamelContextLifecycle extends AutoCloseable {
 
     /**
      * Builds the CamelContext.
-     *
+     * <p/>
      * This phase is intended for frameworks or runtimes that are capable of performing build-time optimizations such as
      * with camel-quarkus.
      */
@@ -119,7 +128,7 @@ public interface CamelContextLifecycle extends AutoCloseable {
     /**
      * Shutdown the CamelContext, which means it cannot be started again.
      * <p/>
-     * See more details at the class-level javadoc at {@link CamelContext}.
+     * See more details at the class-level Javadoc at {@link CamelContext}.
      */
     void shutdown();
 

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

@@ -19,7 +19,13 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Base class for all Camel checked exceptions typically thrown by a {@link Processor}
+ * Base class for all Camel <i>checked</i> exceptions, typically thrown from a {@link Processor} or other lifecycle step
+ * that already declares {@code throws Exception}.
+ * <p/>
+ * Prefer {@link RuntimeCamelException} (or one of its subclasses such as {@link CamelExchangeException}) for failures
+ * raised across API boundaries that do not declare a checked throws clause.
+ *
+ * @see RuntimeCamelException
  */
 public class CamelException extends Exception {
 

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

@@ -21,7 +21,13 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * An exception caused by a specific message {@link Exchange}
+ * A {@link CamelException} that carries the {@link Exchange} whose processing triggered the failure.
+ * <p/>
+ * Used by Camel routing internals to attach exchange context to a failure so error handlers, the dead-letter channel
+ * and onException clauses can inspect headers, properties and the in-flight {@link Message}. The reference is
+ * {@code transient} because exchanges are not guaranteed to be serializable.
+ *
+ * @see Exchange
  */
 public class CamelExchangeException extends CamelException {
     private static final @Serial long serialVersionUID = -8721487431101572630L;

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

@@ -23,32 +23,39 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Catalog level interface for the {@link CamelContext}
+ * Catalog-level extension of {@link CamelContext} that exposes the JSON schema metadata Camel publishes for the
+ * {@link Component}s, {@link DataFormat}s, {@link Language}s and EIPs available at runtime.
+ * <p/>
+ * The catalog data is the same information surfaced by the
+ * <a href="https://camel.apache.org/manual/camel-catalog.html">Camel Catalog</a> tooling and is used by Camel JBang,
+ * IDE plugins, Karaf shell commands and the management/console layer to inspect what is loaded in a running
+ * application.
  *
+ * @see   CamelContext
  * @since 3.0
  */
 public interface CatalogCamelContext extends CamelContext {
 
     /**
      * Returns the JSON schema representation of the component and endpoint parameters for the given component name.
      *
-     * @return the json or <tt>null</tt> if the component is <b>not</b> built with JSON schema support
+     * @return the JSON or <tt>null</tt> if the component is <b>not</b> built with JSON schema support
      */
     @Nullable
     String getComponentParameterJsonSchema(String componentName) throws IOException;
 
     /**
      * Returns the JSON schema representation of the {@link DataFormat} parameters for the given data format name.
      *
-     * @return the json or <tt>null</tt> if the data format does not exist
+     * @return the JSON or <tt>null</tt> if the data format does not exist
      */
     @Nullable
     String getDataFormatParameterJsonSchema(String dataFormatName) throws IOException;
 
     /**
      * Returns the JSON schema representation of the {@link Language} parameters for the given language name.
      *
-     * @return the json or <tt>null</tt> if the language does not exist
+     * @return the JSON or <tt>null</tt> if the language does not exist
      */
     @Nullable
     String getLanguageParameterJsonSchema(String languageName) throws IOException;
@@ -57,7 +64,7 @@ public interface CatalogCamelContext extends CamelContext {
      * Returns the JSON schema representation of the {@link org.apache.camel.spi.DataTypeTransformer} parameters for the
      * given transformer name.
      *
-     * @return the json or <tt>null</tt> if the transformer does not exist
+     * @return the JSON or <tt>null</tt> if the transformer does not exist
      */
     @Nullable
     String getTransformerParameterJsonSchema(String transformerName) throws IOException;
@@ -66,23 +73,23 @@ public interface CatalogCamelContext extends CamelContext {
      * Returns the JSON schema representation of the {@link org.apache.camel.spi.annotations.DevConsole} parameters for
      * the given dev-console name.
      *
-     * @return the json or <tt>null</tt> if the dev-console does not exist
+     * @return the JSON or <tt>null</tt> if the dev-console does not exist
      */
     @Nullable
     String getDevConsoleParameterJsonSchema(String devConsoleName) throws IOException;
 
     /**
      * Returns the JSON schema representation of the EIP parameters for the given EIP name.
      *
-     * @return the json or <tt>null</tt> if the EIP does not exist
+     * @return the JSON or <tt>null</tt> if the EIP does not exist
      */
     @Nullable
     String getEipParameterJsonSchema(String eipName) throws IOException;
 
     /**
      * Returns the JSON schema representation of the pojo bean parameters for the given bean name.
      *
-     * @return the json or <tt>null</tt> if the pojo bean does not exist
+     * @return the JSON or <tt>null</tt> if the pojo bean does not exist
      */
     @Nullable
     String getPojoBeanParameterJsonSchema(String name) throws IOException;

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

@@ -18,8 +18,12 @@
 package org.apache.camel;
 
 /**
- * Context events that can be traced by an {@link org.apache.camel.clock.EventClock}
+ * Lifecycle events of a {@link CamelContext} that can be timestamped via an {@link org.apache.camel.clock.EventClock}.
+ * <p/>
+ * Used by Camel to record when the context was first booted and when it actually started, so tools and metrics can
+ * report startup timings.
  *
+ * @see   CamelContext#getClock()
  * @since 4.4
  */
 public enum ContextEvents {

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

@@ -46,9 +46,14 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Extended {@link CamelContext} which contains the methods and APIs that are not primary intended for Camel end users
- * but for SPI, custom components, or more advanced used-cases with Camel.
+ * Internal extension surface of {@link CamelContext}: methods and SPI hooks that custom components, data formats,
+ * languages, route policies and tooling may need, but that are <b>not</b> part of the end-user facing API.
+ * <p/>
+ * Obtained via {@link CamelContext#getCamelContextExtension()}. End-user route code should depend only on
+ * {@link CamelContext}; everything in this interface should be considered an internal contract that may change between
+ * minor releases.
  *
+ * @see   CamelContext#getCamelContextExtension()
  * @since 3.0
  */
 public interface ExtendedCamelContext {

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

@@ -21,7 +21,10 @@
 import static org.apache.camel.util.URISupport.sanitizeUri;
 
 /**
- * Thrown if Camel failed to create a consumer for a given endpoint.
+ * Thrown when an {@link Endpoint} cannot produce a {@link Consumer}, for example because the endpoint URI is not
+ * consumer-capable, required options are missing, or an underlying client connection cannot be opened.
+ * <p/>
+ * The originating endpoint URI is sanitized (credentials removed) before being included in the message.
  */
 public class FailedToCreateConsumerException extends RuntimeCamelException {
 

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

@@ -21,7 +21,10 @@
 import static org.apache.camel.util.URISupport.sanitizeUri;
 
 /**
- * Thrown if Camel failed to create a producer for a given endpoint.
+ * Thrown when an {@link Endpoint} cannot produce a {@link Producer}, for example because the endpoint URI is not
+ * producer-capable, required options are missing, or an underlying client connection cannot be opened.
+ * <p/>
+ * The originating endpoint URI is sanitized (credentials removed) before being included in the message.
  */
 public class FailedToCreateProducerException extends RuntimeCamelException {
 

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

@@ -22,7 +22,11 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Exception when failing to create a {@link org.apache.camel.Route}.
+ * Thrown when Camel cannot build a {@link Route} from a {@link RoutesBuilder} or route model, for example because an
+ * {@link Endpoint} cannot be resolved, a referenced bean or processor is missing, or DSL validation fails.
+ * <p/>
+ * Distinct from {@link FailedToStartRouteException}, which signals that a successfully built route failed during the
+ * start phase of the {@link CamelContext} lifecycle.
  */
 public class FailedToCreateRouteException extends RuntimeCamelException {
 

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

@@ -19,7 +19,10 @@
 import java.util.Objects;
 
 /**
- * Exception when failing to start a {@link Component}.
+ * Thrown when a {@link Component} fails to start as part of the {@link CamelContext} startup sequence.
+ * <p/>
+ * Carries the component name so the error message points at the offending component (typically the URI scheme used in
+ * route DSL, e.g. {@code kafka}, {@code http}).
  *
  * @since 3.9
  */

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

@@ -21,7 +21,11 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Exception when failing to start a {@link Route}.
+ * Thrown when a previously built {@link Route} fails to start as part of the {@link CamelContext} startup or a
+ * {@link org.apache.camel.spi.RouteController} {@code startRoute} call.
+ * <p/>
+ * Carries the failing {@code routeId} and the source location (where available) so error messages can point at the
+ * offending DSL. For failures during route construction itself use {@link FailedToCreateRouteException}.
  */
 public class FailedToStartRouteException extends RuntimeCamelException {
 

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

@@ -22,7 +22,15 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Base class for all Camel unchecked exceptions.
+ * Base class for all unchecked exceptions thrown by Camel itself.
+ * <p/>
+ * Used by Camel when it cannot propagate a checked {@link Exception} through an API that does not declare one (for
+ * example inside a {@link Processor} chain). The static {@link #wrapRuntimeCamelException(Throwable)} and
+ * {@link #wrapRuntimeException(Throwable)} helpers preserve the original cause unchanged when it is already unchecked,
+ * so wrapping a {@link Throwable} from a unit of work is idempotent.
+ *
+ * @see CamelException
+ * @see CamelExecutionException
  */
 public class RuntimeCamelException extends RuntimeException {
     private static final @Serial long serialVersionUID = 8046489554418284257L;

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

@@ -19,7 +19,19 @@
 import java.io.IOException;
 
 /**
- * Represents the core lifecycle API for services which can be initialized, started and stopped
+ * Core lifecycle contract for every managed object inside a {@link CamelContext}: build → init → start →
+ * stop → close.
+ * <p/>
+ * {@link Component}, {@link Endpoint}, {@link Consumer}, {@link Producer}, {@link Route} and most SPI plug-ins extend
+ * {@link Service} (often via {@code ServiceSupport} in {@code camel-support}). The {@link CamelContext} drives the
+ * lifecycle of registered services so that resources (threads, connections, files, ...) are acquired and released in
+ * the right order.
+ * <p/>
+ * Sub-interfaces extend this contract: {@link StatefulService} exposes the current {@link ServiceStatus},
+ * {@link SuspendableService} adds suspend/resume, and {@link ShutdownableService} adds an explicit shutdown step.
+ *
+ * @see ServiceStatus
+ * @see StatefulService
  */
 public interface Service extends AutoCloseable {
 

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

@@ -19,7 +19,14 @@
 import java.io.Serializable;
 
 /**
- * Represents the status of a {@link Service} instance
+ * The current lifecycle state of a {@link Service} (or {@link StatefulService}) as it transitions between Initializing,
+ * Started, Suspended and Stopped.
+ * <p/>
+ * Returned by {@link StatefulService#getStatus()} and used throughout Camel for state-dependent checks (e.g.
+ * {@link #isStartable()}, {@link #isStoppable()}, {@link #isSuspendable()}).
+ *
+ * @see Service
+ * @see StatefulService
  */
 public enum ServiceStatus implements Serializable {
     /** The service is being initialized. */

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

@@ -17,7 +17,13 @@
 package org.apache.camel;
 
 /**
- * A {@link Service} which has all the lifecycle events and offers details about its current state.
+ * A {@link Service} that exposes its current {@link ServiceStatus} together with the full lifecycle, including
+ * suspend/resume from {@link SuspendableService} and shutdown from {@link ShutdownableService}.
+ * <p/>
+ * Most Camel built-in services extend this contract via {@code ServiceSupport} in {@code camel-support}, so route code
+ * can ask any service whether it is started, suspended, stopping, etc.
+ *
+ * @see ServiceStatus
  */
 public interface StatefulService extends SuspendableService, ShutdownableService {