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 634aee210793 chore: add Exchange, Variables, Message, and Startup
Order sections to CamelContext docs
634aee210793 is described below
commit 634aee210793a15d51f2f1d39f45d19df85aa6d0
Author: Claus Ibsen <[email protected]>
AuthorDate: Thu Jul 2 17:58:22 2026 +0200
chore: add Exchange, Variables, Message, and Startup Order sections to
CamelContext docs
Adds missing core concept sections to the CamelContext architecture
page: Exchange structure (In message, properties, exception), Variables
as the recommended alternative to exchange properties, Message parts
(body, headers, attachments), and CamelContext startup order.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
---
.../modules/ROOT/pages/camelcontext.adoc | 57 +++++++++++++++++++++-
1 file changed, 55 insertions(+), 2 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/camelcontext.adoc
b/docs/user-manual/modules/ROOT/pages/camelcontext.adoc
index 07004b7218f7..01bdd29b197e 100644
--- a/docs/user-manual/modules/ROOT/pages/camelcontext.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camelcontext.adoc
@@ -117,6 +117,45 @@ from the previous step is the input (in) message of the
next. In many cases, pro
is reused. The xref:exchange-pattern.adoc[exchange pattern] of the exchange
determines, at the end of a route, whether a reply needs to be sent back to the
caller of the route.
If the exchange pattern (MEP) is `InOnly`, no reply will be sent back. If it’s
`InOut`, Camel will take the out message from the last step and return it.
+=== Exchange
+
+The xref:exchange.adoc[Exchange] is the message container that flows through a
route. Every time a consumer receives a message, it wraps it in an Exchange and
sends it through the route's processor chain.
+
+An Exchange holds:
+
+* *In Message* — the current message being processed. Most processors read and
modify the In message directly.
+* *Exchange Properties* — a `Map<String, Object>` of metadata scoped to the
exchange. Properties are _not_ propagated to external systems — they are only
visible within the route. Use properties to pass state between processors in
the same route.
+* *Exception* — set when processing fails. Used by
xref:error-handler.adoc[error handlers] and
xref:exception-clause.adoc[exception clauses] to determine how to handle the
failure.
+
+The xref:exchange-pattern.adoc[Exchange Pattern] (MEP) determines whether the
exchange is one-way (`InOnly`) or request-reply (`InOut`). For `InOut`, Camel
returns the final message as the reply to the caller.
+
+=== Variables
+
+xref:variables.adoc[Variables] are the recommended way to store user data
during routing instead of exchange properties.
+
+Exchange properties are also used internally by Camel and some EIPs and
components, which can lead to naming conflicts or unexpected behavior.
Variables are exclusively for end users — Camel will never set or read your
variables internally.
+
+Variables can be scoped at different levels:
+
+* *Exchange* (default) — private to the current exchange, same as exchange
properties but without the risk of collisions with Camel internals
+* *Route* — shared across all exchanges in a specific route
+* *Group* — shared across a named group of routes
+* *Global* — shared across the entire `CamelContext`
+
+Variables also integrate with commonly used EIPs (`to`, `enrich`, `poll`,
`unmarshal`, etc.) via `variableSend` and `variableReceive` options, making it
easy to gather data from external systems without modifying the current message.
+
+See xref:variables.adoc[Variables] for the full reference.
+
+=== Message
+
+A xref:exchange.adoc[Message] has three parts:
+
+* *Body* — the payload. Can be any Java type. Camel's
xref:type-converter.adoc[type converter] system automatically converts between
types when needed (for example, `String` to `InputStream`, JSON to POJO,
`byte[]` to `String`).
+* *Headers* — a `Map<String, Object>` of metadata. Headers are propagated to
and from external systems by producers and consumers. For example, the File
component sets `CamelFileName`, and the HTTP component maps HTTP headers.
Camel-internal headers use the `Camel` prefix.
+* *Attachments* — binary attachments (used mainly with mail and SOAP
components).
+
+NOTE: Headers and exchange properties are different. Headers travel with the
message and can be sent to external systems. Exchange properties are
route-scoped and never leave the exchange.
+
=== Component
xref:components::index.adoc[Components] are the main extension point in Camel.
@@ -205,8 +244,22 @@ when using the
xref:components:eips:pollEnrich-eip.adoc[Poll Enrich] EIP, or fro
creating a `PollingConsumer` instance via the `createPollingConsumer()` method
from `Endpoint`.
+== Startup Order
+
+When the `CamelContext` starts, it initializes services in a specific order:
+
+. *CamelContext* — initializes the registry, type converters, and internal
services
+. *Components* — component instances are created (or lazy-loaded on first use)
+. *Endpoints* — endpoints referenced by routes are resolved and created
+. *Routes* — route definitions are built into the processor chain
+. *Consumers* — consumers start last, so all routes, endpoints, and processors
are fully ready before any messages flow in
+
+This order ensures that when the first message arrives, everything it needs is
already initialized. Consumers starting last is important — it prevents
messages from arriving before the route is ready to process them.
+
+Routes can be started and stopped individually at runtime using the
`CamelContext` or via JMX.
+
+See xref:lifecycle.adoc[Lifecycle] for the full lifecycle details including
suspend/resume and graceful shutdown.
+
== See Also
See the following for high-level xref:architecture.adoc[architecture] of
Apache Camel.
-
-See xref:lifecycle.adoc[Lifecycle] to understand the overall lifecycle of the
`CamelContext`.
