From 249d8137cb007b520db8469756bfd922fcb97ad9 Mon Sep 17 00:00:00 2001 From: Adriano Machado <60320+ammachado@users.noreply.github.com> Date: Mon, 18 May 2026 13:11:39 -0400 Subject: [PATCH 1/2] CAMEL-23535: docs - Audit Get Started, Working with Camel Core and Advanced Camel Core Guides Refresh outdated version references, remove duplicate xrefs, fix mislabeled link, correct typos and misleading wording across the three core docs landing pages. Co-Authored-By: Claude Opus 4.7 rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED --- .../pages/index.adoc | 6 ++-- .../modules/getting-started/pages/index.adoc | 30 +++++++++---------- .../working-with-camel-core/pages/index.adoc | 8 ++--- 3 files changed, 21 insertions(+), 23 deletions(-) diff --git a/docs/main/modules/advanced-camel-core-guides/pages/index.adoc b/docs/main/modules/advanced-camel-core-guides/pages/index.adoc index 7aec83366c431..99508140a8ac4 100644 --- a/docs/main/modules/advanced-camel-core-guides/pages/index.adoc +++ b/docs/main/modules/advanced-camel-core-guides/pages/index.adoc @@ -1,8 +1,8 @@ = Advanced Camel Core Guides -In these page you can find guides and documents that can help you to discover how to observe, scale and debug integrations. You can Learn about more advanced features of Camel Core and how you can build upon those for creating highly customized integrations for all projects and products. +On this page you can find guides and documents that can help you to discover how to observe, scale and debug integrations. You can learn about more advanced features of Camel Core and how you can build upon those for creating highly customized integrations for all projects and products. -* xref:manual::camel-component-maven-plugin.adoc[Camel Maven Component] +* xref:manual::camel-component-maven-plugin.adoc[Camel Component Maven Plugin] * xref:manual::batch-consumer.adoc[Batch Consumer] * xref:manual::graceful-shutdown.adoc[Graceful Shutdown] * xref:manual::backlog-debugger.adoc[Backlog Debugger] @@ -41,4 +41,4 @@ If you are looking at contributing to Apache Camel, these guides may also help: * xref:manual::release-guide.adoc[Release Guide] * xref:manual::release-guide-website.adoc[Release Guide for the Website] -You can find additional documentation in the xref:manual::architecture.adoc[architecture documentation] in the old user manual. +You can find additional documentation in the xref:manual::architecture.adoc[architecture documentation] in the user manual. diff --git a/docs/main/modules/getting-started/pages/index.adoc b/docs/main/modules/getting-started/pages/index.adoc index d7604e1e2299c..ffbcce99b514a 100644 --- a/docs/main/modules/getting-started/pages/index.adoc +++ b/docs/main/modules/getting-started/pages/index.adoc @@ -11,7 +11,7 @@ Books about design patterns document the existing best practices within a partic A famous book about design patterns is the http://www.amazon.com/Enterprise-Integration-Patterns-Designing-Deploying/dp/0321200683[_Enterprise Integration Patterns: Designing, Building, and Deploying Messaging -Solutions_] written by Gregor Hohpe and Bobby Wolf. The E.I.P. book, as it is known, describes 65 design patterns for asynchronous messaging systems. The book gives each of them a name and an image - intended to be used in architectural diagrams. +Solutions_] written by Gregor Hohpe and Bobby Woolf. The E.I.P. book, as it is known, describes 65 design patterns for asynchronous messaging systems. The book gives each of them a name and an image - intended to be used in architectural diagrams. [[BookGettingStarted-TheCamelProject]] === The Apache Camel Core project @@ -48,11 +48,11 @@ The Javadoc API that are the most relevant for Camel end users are in the follow [[BookGettingStarted-CreatingYourFirstProject]] == Creating your first project -We'll start this guide by creating a simple integration. You need to have https://maven.apache.org/[Apache Maven] and a https://adoptium.net/temurin/[JDK] version 11 or greater installed on your system. +We'll start this guide by creating a simple integration. You need to have https://maven.apache.org/[Apache Maven] 3.9.6 or greater and a https://adoptium.net/temurin/[JDK] version 17 or greater installed on your system. [NOTE] ==== -We strongly recommend you use an LTS version of Java (i.e., 11 or 17). We regularly test Camel in our continuous integration (CI) environment using Java's LTS versions. +We strongly recommend you use an LTS version of Java (i.e., 17 or 21). We regularly test Camel in our continuous integration (CI) environment using Java's LTS versions. ==== === Generating the project @@ -63,13 +63,13 @@ Run this command to create your first Camel Core project: [source,bash] ---- -mvn archetype:generate -B -DarchetypeGroupId=org.apache.camel.archetypes -DarchetypeArtifactId=camel-archetype-java -DarchetypeVersion=3.18.4 -Dpackage=org.apache.camel.learn -DgroupId=org.apache.camel.learn -DartifactId=first-camel-integration -Dversion=1.0.0-SNAPSHOT +mvn archetype:generate -B -DarchetypeGroupId=org.apache.camel.archetypes -DarchetypeArtifactId=camel-archetype-java -DarchetypeVersion=4.20.0 -Dpackage=org.apache.camel.learn -DgroupId=org.apache.camel.learn -DartifactId=first-camel-integration -Dversion=1.0.0-SNAPSHOT ---- If you have never used archetypes before, the command looks lengthy. We'll explain the relevant arguments: * `-DarchetypeArtifactId`: this is the ID of the archetype to use (i.e., which of the templates from Camel Core to use - `camel-archetype-java` in this case) -* `-DarchetypeVersion`: this is the version of the archetype to use. It is also the same version of Camel to use for the example. We are using `3.18.4` in this example. +* `-DarchetypeVersion`: this is the version of the archetype to use. It is also the same version of Camel to use for the example. We are using `4.20.0` in this example. Check https://camel.apache.org/download/[the Camel download page] for the latest released version. * `-Dpackage`: the package name for the project you are creating. We'll use `org.apache.camel.learn` in all this guide. * `-DgroupId`: the group ID for the project you are creating. We'll use `org.apache.camel.learn` in all this guide. * `-DartifactId`: the artifact name for the project you are creating. @@ -101,15 +101,15 @@ After you run the command above, you should have the following messages: [source,bash] ---- ... -[che.camel.learn.MainApp.main()] MainSupport INFO Apache Camel (Main) 3.18.4 is starting +[che.camel.learn.MainApp.main()] MainSupport INFO Apache Camel (Main) 4.20.0 is starting [che.camel.learn.MainApp.main()] BaseMainSupport INFO Auto-configuration summary [che.camel.learn.MainApp.main()] XPathBuilder INFO Created default XPathFactory com.sun.org.apache.xpath.internal.jaxp.XPathFactoryImpl@33cc7a16 [che.camel.learn.MainApp.main()] FileEndpoint INFO Endpoint is configured with noop=true so forcing endpoint to be idempotent as well [che.camel.learn.MainApp.main()] FileEndpoint INFO Using default memory based idempotent repository with cache max size: 1000 -[che.camel.learn.MainApp.main()] AbstractCamelContext INFO Apache Camel 3.18.4 (camel-1) is starting +[che.camel.learn.MainApp.main()] AbstractCamelContext INFO Apache Camel 4.20.0 (camel-1) is starting [che.camel.learn.MainApp.main()] AbstractCamelContext INFO Routes startup (started:1) [che.camel.learn.MainApp.main()] AbstractCamelContext INFO Started route1 (file://src/data) -[che.camel.learn.MainApp.main()] AbstractCamelContext INFO Apache Camel 3.18.4 (camel-1) started in 89ms (build:12ms init:68ms start:9ms JVM-uptime:1s) +[che.camel.learn.MainApp.main()] AbstractCamelContext INFO Apache Camel 4.20.0 (camel-1) started in 89ms (build:12ms init:68ms start:9ms JVM-uptime:1s) [che.camel.learn.MainApp.main()] MainSupport INFO Waiting until complete: Duration max 2 messages processed [1) thread #1 - file://src/data] route1 INFO Other message [1) thread #1 - file://src/data] route1 INFO UK message @@ -117,7 +117,7 @@ After you run the command above, you should have the following messages: If you can see an output like that on your terminal, it means the integration has run well. -The integration you have just run consumed two files and copied them to a directory based on their contents. You can check it out yourself but looking at the `target/messages` directory within the project: +The integration you have just run consumed two files and copied them to a directory based on their contents. You can check it out yourself by looking at the `target/messages` directory within the project: [NOTE] ==== @@ -141,12 +141,12 @@ target/messages/uk/message1.xml [NOTE] ==== -Use the Windows Explorer or the Windows equivalent of the `find` command available on Linux, macOS or *BSDs. +The `find` command is available on Linux, macOS and *BSDs. On Windows, use Windows Explorer or the equivalent shell command (such as `dir /s /b`). ==== == Understanding the project -The integration you created implements a pattern (E.I.P.) called xref:components:eips:choice-eip.adoc[Content Based Router]. The Camel implementation of this pattern allows you to implement logic that route messages based on their content. +The integration you created implements a pattern (E.I.P.) called xref:components:eips:choice-eip.adoc[Content Based Router]. The Camel implementation of this pattern allows you to implement logic that routes messages based on their content. More specifically, this integration looks at the content of the XML files in the `src/data` directory. If the content of the element `city` is London, then it moves the file to the directory `target/messages/uk`. Otherwise, it moves the file to the directory `target/messages/others`. @@ -239,7 +239,7 @@ Camel makes extensive use of xref:manual::uris.adoc[URIs] to allow you to refer Some Camel methods take a parameter that is a https://en.wikipedia.org/wiki/Uniform_Resource_Identifier[URI] string. People usually know that a URI is "something like a https://en.wikipedia.org/wiki/URL[URL]" but do not always understand the relationship between URI and an URL or its relationship with other acronyms such as https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier[IRI] and https://en.wikipedia.org/wiki/Uniform_Resource_Name[URN]. -Most people are familiar with _URLs_ (uniform resource locators), such as `\http://...`, `\ftp://...`, `\mailto:...:`. A URL specifies the _location_ of a resource. +Most people are familiar with _URLs_ (uniform resource locators), such as `\http://...`, `\ftp://...`, `\mailto:...`. A URL specifies the _location_ of a resource. A URN is a wrapper for different "unique identifier" schemes. The syntax of a URN is `urn::`. A URN uniquely identifies a _resource_ (i.e.:, a book, person, or piece of equipment). By itself, a URN does not specify the _location_ of the resource. @@ -344,7 +344,7 @@ our documentation contains an in-depth overview of the xref:manual::camelcontext [[BookGettingStarted-Components]] === Components -Components are another fundamental building block of Apache Camel and are used to connect routes to a wide variety of external systems and services. Camel comes with a large number of built-in components that provide connectivity to a wide range of technologies and protocols, such as HTTP, JMS, file, and many others. You can also create a custom components if the built-in components do not meet your needs. +Components are another fundamental building block of Apache Camel and are used to connect routes to a wide variety of external systems and services. Camel comes with a large number of built-in components that provide connectivity to a wide range of technologies and protocols, such as HTTP, JMS, file, and many others. You can also create custom components if the built-in components do not meet your needs. Typically, Camel-based applications shouldn't need to interact directly with a component. However, there are some circumstances where manipulating the component may be beneficial for the performance, operation, or scalability of the application. Our documentation contains an in-depth overview of the xref:manual::component.adoc[Component] if you want to learn more about it, including important details necessary to write your own. @@ -375,13 +375,13 @@ When writing routes, you may use processors to execute more complex logic on the ---- public void process(Exchange exchange) { final String body = exchange.getMessage().getBody(String.class); - System.out.println(“Updated body: “ + body.replace(“city”, “county”)); + System.out.println("Updated body: " + body.replace("city", "county")); // ... more code here } public void configure() { - from(“file:src/data?noop=true”) + from("file:src/data?noop=true") .process(this::process); } ---- diff --git a/docs/main/modules/working-with-camel-core/pages/index.adoc b/docs/main/modules/working-with-camel-core/pages/index.adoc index 0d6398a7fe811..e8c0b9bd72073 100644 --- a/docs/main/modules/working-with-camel-core/pages/index.adoc +++ b/docs/main/modules/working-with-camel-core/pages/index.adoc @@ -2,7 +2,7 @@ == Context -The xref:manual::camelcontext.adoc[Camel Context] is the hearth of Apache Camel, which holds everything together. +The xref:manual::camelcontext.adoc[Camel Context] is the heart of Apache Camel, which holds everything together. If you are not familiar with Apache Camel, then we recommend reading the xref:manual::camelcontext.adoc[Camel Context] first before coming back here. @@ -18,7 +18,7 @@ In other words, a Camel _route_ is where the integration flow is defined. For ex If you have basic knowledge about _routes_, you can use the following guides to learn how to write them in different languages, handle errors, and customize them. * Content -** xref:manual::camelcontext.adoc[Camel Context]: the hearth of Apache Camel +** xref:manual::camelcontext.adoc[Camel Context]: the heart of Apache Camel * Routes (Basic + DSL) ** xref:manual::java-dsl.adoc[Java DSL]: the default language to write _routes_. @@ -79,7 +79,6 @@ Learn about additional ways to customize your integrations. Explore alternatives * Context -** xref:manual::camelcontext.adoc[Camel Context] ** xref:manual::camelcontext-autoconfigure.adoc[Camel Context Auto Configuration] ** xref:manual::advanced-configuration-of-camelcontext-using-spring.adoc[Advanced Configuration of Camel Context] * Running Camel Applications and Other Runtime Guides @@ -108,9 +107,8 @@ Learn about additional ways to customize your integrations. Explore alternatives ** xref:manual::spring.adoc[Spring] ** xref:manual::spring-xml-extensions.adoc[Spring XML Extensions] ** xref:manual::validator.adoc[Validator] -** xref:manual::variables.adoc[Variables] ** xref:manual::what-are-the-dependencies.adoc[Camel Requirements] ** xref:manual::testing.adoc[Testing] -You can find additional documentation in the xref:manual::architecture.adoc[architecture documentation] in the old user manual. +You can find additional documentation in the xref:manual::architecture.adoc[architecture documentation] in the user manual. From fce1aa66ab688e31a6d10e80988ccddee3ee0d1f Mon Sep 17 00:00:00 2001 From: Adriano Machado <60320+ammachado@users.noreply.github.com> Date: Mon, 18 May 2026 15:14:29 -0400 Subject: [PATCH 2/2] CAMEL-23535: camel-api - enhance class-level javadoc for lifecycle and context types Expand class-level javadoc on CamelContext, Service, exceptions and related lifecycle types in core/camel-api to better describe their role, when they apply, and how they relate to sibling types. Co-Authored-By: Claude Opus 4.7 rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED --- .../apache/camel/AlreadyStoppedException.java | 6 ++++- .../java/org/apache/camel/CamelContext.java | 21 +++++++++++++---- .../org/apache/camel/CamelContextAware.java | 12 +++++++++- .../apache/camel/CamelContextLifecycle.java | 19 +++++++++++---- .../java/org/apache/camel/CamelException.java | 8 ++++++- .../apache/camel/CamelExchangeException.java | 8 ++++++- .../org/apache/camel/CatalogCamelContext.java | 23 ++++++++++++------- .../java/org/apache/camel/ContextEvents.java | 6 ++++- .../apache/camel/ExtendedCamelContext.java | 9 ++++++-- .../FailedToCreateConsumerException.java | 5 +++- .../FailedToCreateProducerException.java | 5 +++- .../camel/FailedToCreateRouteException.java | 6 ++++- .../FailedToStartComponentException.java | 5 +++- .../camel/FailedToStartRouteException.java | 6 ++++- .../apache/camel/RuntimeCamelException.java | 10 +++++++- .../main/java/org/apache/camel/Service.java | 14 ++++++++++- .../java/org/apache/camel/ServiceStatus.java | 9 +++++++- .../org/apache/camel/StatefulService.java | 8 ++++++- 18 files changed, 146 insertions(+), 34 deletions(-) diff --git a/core/camel-api/src/main/java/org/apache/camel/AlreadyStoppedException.java b/core/camel-api/src/main/java/org/apache/camel/AlreadyStoppedException.java index 2e37d83a7540b..44a7a2576df76 100644 --- a/core/camel-api/src/main/java/org/apache/camel/AlreadyStoppedException.java +++ b/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. + *

+ * 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 { diff --git a/core/camel-api/src/main/java/org/apache/camel/CamelContext.java b/core/camel-api/src/main/java/org/apache/camel/CamelContext.java index 26f41ef1982ae..b032c92853b39 100644 --- a/core/camel-api/src/main/java/org/apache/camel/CamelContext.java +++ b/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 CamelContext 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. + *

+ * 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. *

* The CamelContext offers the following methods {@link CamelContextLifecycle} to control the lifecycle: *

    *
  • {@link #start()} - to start
    • - *
  • {@link #stop()} - to shutdown (will stop all routes/components/endpoints etc and clear internal state/cache)
    • - *
  • {@link #suspend()} - to pause routing messages
    • - *
  • {@link #resume()} - to resume after a suspend
    • + *
  • {@link #stop()} - to shut down (will stop all routes/components/endpoints etc. and clear internal + * state/cache)
    • + *
  • {@link #suspend()} - to pause message routing message
    • + *
  • {@link #resume()} - to resume after a suspended execution
    • *
*

* Notice: {@link #stop()} and {@link #suspend()} will gracefully stop/suspend routes ensuring any messages in @@ -83,6 +90,10 @@ *

* 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 { diff --git a/core/camel-api/src/main/java/org/apache/camel/CamelContextAware.java b/core/camel-api/src/main/java/org/apache/camel/CamelContextAware.java index 42f3275c71106..6618e10589762 100644 --- a/core/camel-api/src/main/java/org/apache/camel/CamelContextAware.java +++ b/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}. + *

+ * 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. + *

+ * 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 { diff --git a/core/camel-api/src/main/java/org/apache/camel/CamelContextLifecycle.java b/core/camel-api/src/main/java/org/apache/camel/CamelContextLifecycle.java index 7cc49688a4ac4..659196bfe631c 100644 --- a/core/camel-api/src/main/java/org/apache/camel/CamelContextLifecycle.java +++ b/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. + *

+ * Extracted from {@link CamelContext} so the lifecycle surface can be referenced independently of the rest of the + * context configuration API. See Camel lifecycle for the + * full description of states and transitions. + *

+ * 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} (important: the start method is not blocked, see more details in the * {@link Main} documentation for running Camel Standalone). *

- * 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). *

- * 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. - * + *

* 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. *

- * See more details at the class-level javadoc at {@link CamelContext}. + * See more details at the class-level Javadoc at {@link CamelContext}. */ void shutdown(); diff --git a/core/camel-api/src/main/java/org/apache/camel/CamelException.java b/core/camel-api/src/main/java/org/apache/camel/CamelException.java index 985f15ab82d81..326c65da29c8b 100644 --- a/core/camel-api/src/main/java/org/apache/camel/CamelException.java +++ b/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 checked exceptions, typically thrown from a {@link Processor} or other lifecycle step + * that already declares {@code throws Exception}. + *

+ * 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 { diff --git a/core/camel-api/src/main/java/org/apache/camel/CamelExchangeException.java b/core/camel-api/src/main/java/org/apache/camel/CamelExchangeException.java index d9a319841cf35..ca7c7100468bd 100644 --- a/core/camel-api/src/main/java/org/apache/camel/CamelExchangeException.java +++ b/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. + *

+ * 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; diff --git a/core/camel-api/src/main/java/org/apache/camel/CatalogCamelContext.java b/core/camel-api/src/main/java/org/apache/camel/CatalogCamelContext.java index c8a154e62056a..8ebbb794054fd 100644 --- a/core/camel-api/src/main/java/org/apache/camel/CatalogCamelContext.java +++ b/core/camel-api/src/main/java/org/apache/camel/CatalogCamelContext.java @@ -23,8 +23,15 @@ 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. + *

+ * The catalog data is the same information surfaced by the + * Camel Catalog 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 { @@ -32,7 +39,7 @@ 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 null if the component is not built with JSON schema support + * @return the JSON or null if the component is not built with JSON schema support */ @Nullable String getComponentParameterJsonSchema(String componentName) throws IOException; @@ -40,7 +47,7 @@ public interface CatalogCamelContext extends CamelContext { /** * Returns the JSON schema representation of the {@link DataFormat} parameters for the given data format name. * - * @return the json or null if the data format does not exist + * @return the JSON or null if the data format does not exist */ @Nullable String getDataFormatParameterJsonSchema(String dataFormatName) throws IOException; @@ -48,7 +55,7 @@ public interface CatalogCamelContext extends CamelContext { /** * Returns the JSON schema representation of the {@link Language} parameters for the given language name. * - * @return the json or null if the language does not exist + * @return the JSON or null 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 null if the transformer does not exist + * @return the JSON or null if the transformer does not exist */ @Nullable String getTransformerParameterJsonSchema(String transformerName) throws IOException; @@ -66,7 +73,7 @@ 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 null if the dev-console does not exist + * @return the JSON or null if the dev-console does not exist */ @Nullable String getDevConsoleParameterJsonSchema(String devConsoleName) throws IOException; @@ -74,7 +81,7 @@ public interface CatalogCamelContext extends CamelContext { /** * Returns the JSON schema representation of the EIP parameters for the given EIP name. * - * @return the json or null if the EIP does not exist + * @return the JSON or null if the EIP does not exist */ @Nullable String getEipParameterJsonSchema(String eipName) throws IOException; @@ -82,7 +89,7 @@ public interface CatalogCamelContext extends CamelContext { /** * Returns the JSON schema representation of the pojo bean parameters for the given bean name. * - * @return the json or null if the pojo bean does not exist + * @return the JSON or null if the pojo bean does not exist */ @Nullable String getPojoBeanParameterJsonSchema(String name) throws IOException; diff --git a/core/camel-api/src/main/java/org/apache/camel/ContextEvents.java b/core/camel-api/src/main/java/org/apache/camel/ContextEvents.java index 0a41ccccd65e5..dc1a44b3c4d88 100644 --- a/core/camel-api/src/main/java/org/apache/camel/ContextEvents.java +++ b/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}. + *

+ * 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 { diff --git a/core/camel-api/src/main/java/org/apache/camel/ExtendedCamelContext.java b/core/camel-api/src/main/java/org/apache/camel/ExtendedCamelContext.java index aa52834885fcd..55e411d590942 100644 --- a/core/camel-api/src/main/java/org/apache/camel/ExtendedCamelContext.java +++ b/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 not part of the end-user facing API. + *

+ * 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 { diff --git a/core/camel-api/src/main/java/org/apache/camel/FailedToCreateConsumerException.java b/core/camel-api/src/main/java/org/apache/camel/FailedToCreateConsumerException.java index 6b854ccdd5b55..20d32c247397b 100644 --- a/core/camel-api/src/main/java/org/apache/camel/FailedToCreateConsumerException.java +++ b/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. + *

+ * The originating endpoint URI is sanitized (credentials removed) before being included in the message. */ public class FailedToCreateConsumerException extends RuntimeCamelException { diff --git a/core/camel-api/src/main/java/org/apache/camel/FailedToCreateProducerException.java b/core/camel-api/src/main/java/org/apache/camel/FailedToCreateProducerException.java index 73a245a32e600..7a60d24c2da72 100644 --- a/core/camel-api/src/main/java/org/apache/camel/FailedToCreateProducerException.java +++ b/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. + *

+ * The originating endpoint URI is sanitized (credentials removed) before being included in the message. */ public class FailedToCreateProducerException extends RuntimeCamelException { diff --git a/core/camel-api/src/main/java/org/apache/camel/FailedToCreateRouteException.java b/core/camel-api/src/main/java/org/apache/camel/FailedToCreateRouteException.java index 845fdae4a233d..0ea76d5bb4f44 100644 --- a/core/camel-api/src/main/java/org/apache/camel/FailedToCreateRouteException.java +++ b/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. + *

+ * 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 { diff --git a/core/camel-api/src/main/java/org/apache/camel/FailedToStartComponentException.java b/core/camel-api/src/main/java/org/apache/camel/FailedToStartComponentException.java index b33cf877405ec..0049c1e9b8106 100644 --- a/core/camel-api/src/main/java/org/apache/camel/FailedToStartComponentException.java +++ b/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. + *

+ * 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 */ diff --git a/core/camel-api/src/main/java/org/apache/camel/FailedToStartRouteException.java b/core/camel-api/src/main/java/org/apache/camel/FailedToStartRouteException.java index 5fb55d464b76b..b26eecb23dbed 100644 --- a/core/camel-api/src/main/java/org/apache/camel/FailedToStartRouteException.java +++ b/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. + *

+ * 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 { diff --git a/core/camel-api/src/main/java/org/apache/camel/RuntimeCamelException.java b/core/camel-api/src/main/java/org/apache/camel/RuntimeCamelException.java index e0386eaf1ee97..922c9c36d8c1e 100644 --- a/core/camel-api/src/main/java/org/apache/camel/RuntimeCamelException.java +++ b/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. + *

+ * 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; diff --git a/core/camel-api/src/main/java/org/apache/camel/Service.java b/core/camel-api/src/main/java/org/apache/camel/Service.java index 8d27dd490c6e5..ac7908aa61a79 100644 --- a/core/camel-api/src/main/java/org/apache/camel/Service.java +++ b/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. + *

+ * {@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. + *

+ * 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 { diff --git a/core/camel-api/src/main/java/org/apache/camel/ServiceStatus.java b/core/camel-api/src/main/java/org/apache/camel/ServiceStatus.java index 443de4d566f6d..03e74d7d3da7b 100644 --- a/core/camel-api/src/main/java/org/apache/camel/ServiceStatus.java +++ b/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. + *

+ * 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. */ diff --git a/core/camel-api/src/main/java/org/apache/camel/StatefulService.java b/core/camel-api/src/main/java/org/apache/camel/StatefulService.java index d521465e4d2e4..24a33772ae411 100644 --- a/core/camel-api/src/main/java/org/apache/camel/StatefulService.java +++ b/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}. + *

+ * 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 {