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 75812fb1b44c CAMEL-23535: camel-api - enhance class-level javadoc for
lifecycle and context types (#23311)
75812fb1b44c is described below
commit 75812fb1b44c31cfbcb737e36c5222993e050e22
Author: Adriano Machado <[email protected]>
AuthorDate: Tue May 19 01:09:40 2026 -0400
CAMEL-23535: camel-api - enhance class-level javadoc for lifecycle and
context types (#23311)
* 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 <[email protected]>
rh-pre-commit.version: 2.3.2
rh-pre-commit.check-secrets: ENABLED
* 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 <[email protected]>
rh-pre-commit.version: 2.3.2
rh-pre-commit.check-secrets: ENABLED
---
.../org/apache/camel/AlreadyStoppedException.java | 6 ++++-
.../main/java/org/apache/camel/CamelContext.java | 21 +++++++++++----
.../java/org/apache/camel/CamelContextAware.java | 12 ++++++++-
.../org/apache/camel/CamelContextLifecycle.java | 19 ++++++++++----
.../main/java/org/apache/camel/CamelException.java | 8 +++++-
.../org/apache/camel/CamelExchangeException.java | 8 +++++-
.../java/org/apache/camel/CatalogCamelContext.java | 23 +++++++++++------
.../main/java/org/apache/camel/ContextEvents.java | 6 ++++-
.../org/apache/camel/ExtendedCamelContext.java | 9 +++++--
.../camel/FailedToCreateConsumerException.java | 5 +++-
.../camel/FailedToCreateProducerException.java | 5 +++-
.../apache/camel/FailedToCreateRouteException.java | 6 ++++-
.../camel/FailedToStartComponentException.java | 5 +++-
.../apache/camel/FailedToStartRouteException.java | 6 ++++-
.../org/apache/camel/RuntimeCamelException.java | 10 +++++++-
.../src/main/java/org/apache/camel/Service.java | 14 +++++++++-
.../main/java/org/apache/camel/ServiceStatus.java | 9 ++++++-
.../java/org/apache/camel/StatefulService.java | 8 +++++-
.../advanced-camel-core-guides/pages/index.adoc | 6 ++---
docs/main/modules/getting-started/pages/index.adoc | 30 +++++++++++-----------
.../working-with-camel-core/pages/index.adoc | 8 +++---
21 files changed, 167 insertions(+), 57 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 2e37d83a7540..44a7a2576df7 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.
+ * <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 {
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 26f41ef1982a..b032c92853b3 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.apache.camel.vault.VaultConfiguration;
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 @@ import org.jspecify.annotations.Nullable;
* <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 {
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 42f3275c7110..6618e1058976 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 @@ package org.apache.camel;
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 {
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 7cc49688a4ac..659196bfe631 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.
+ * <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();
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 985f15ab82d8..326c65da29c8 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 @@ package org.apache.camel;
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 {
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 d9a319841cf3..ca7c7100468b 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 java.io.Serial;
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;
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 c8a154e62056..8ebbb794054f 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.apache.camel.spi.Language;
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 {
@@ -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 <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;
@@ -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 <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;
@@ -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 <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,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 <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;
@@ -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 <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;
@@ -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 <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;
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 0a41ccccd65e..dc1a44b3c4d8 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}.
+ * <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 {
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 aa52834885fc..55e411d59094 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.apache.camel.spi.StartupStepRecorder;
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 {
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 6b854ccdd5b5..20d32c247397 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 java.util.Objects;
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 {
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 73a245a32e60..7a60d24c2da7 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 java.util.Objects;
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 {
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 845fdae4a233..0ea76d5bb4f4 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.apache.camel.util.URISupport;
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 {
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 b33cf877405e..0049c1e9b810 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 @@ package org.apache.camel;
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
*/
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 5fb55d464b76..b26eecb23dbe 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 java.util.Objects;
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 {
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 e0386eaf1ee9..922c9c36d8c1 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 java.util.Objects;
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;
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 8d27dd490c6e..ac7908aa61a7 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 @@ package org.apache.camel;
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 {
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 443de4d566f6..03e74d7d3da7 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 @@ package org.apache.camel;
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. */
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 d521465e4d2e..24a33772ae41 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}.
+ * <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 {
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 7aec83366c43..99508140a8ac 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 d7604e1e2299..ffbcce99b514 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:<scheme-name>:<unique-identifier>`. 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 0d6398a7fe81..e8c0b9bd7207 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.
