From 222fadb89c1339033eb937ed5df434ee75293ab7 Mon Sep 17 00:00:00 2001 From: Andrea Cosentino Date: Fri, 29 May 2026 14:23:02 +0200 Subject: [PATCH] CAMEL-23584: docs - sync camel-kafka 4.18 / 4.14 upgrade-guide entries to main The camel-kafka Exchange header constant rename (CAMEL-23584) is being backported to the camel-4.18.x and camel-4.14.x maintenance branches. The version-specific upgrade-guide files on main are the canonical history, so the "potential breaking change" entry for the 4.18 and 4.14 release lines is added here on main (the maintenance-branch backports intentionally omit the upgrade-guide change, per the backport upgrade-guide policy). Adds the "camel-kafka - potential breaking change" section (the kafka.* -> CamelKafka* header constant rename table, the symbolic-vs-literal migration note with a before/after example, the Endpoint DSL accessor note, and the cross-transport HeaderFilterStrategy behaviour note) to both camel-4x-upgrade-guide-4_18.adoc and camel-4x-upgrade-guide-4_14.adoc, matching the entry already present in camel-4x-upgrade-guide-4_21.adoc. Tracker: CAMEL-23577 Reported by Claude Code on behalf of Andrea Cosentino Signed-off-by: Andrea Cosentino --- .../pages/camel-4x-upgrade-guide-4_14.adoc | 69 +++++++++++++++++++ .../pages/camel-4x-upgrade-guide-4_18.adoc | 69 +++++++++++++++++++ 2 files changed, 138 insertions(+) diff --git a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc index 7fc2956a8d7f5..5ae207b4d33da 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc @@ -633,3 +633,72 @@ between the transport `from` and the `dns:` `to`. Allowing untrusted senders to drive `DnsConstants.DNS_SERVER` (the recursive resolver target in `dns:dig`) without such a mapping step is not the intended use of the component. + +=== camel-kafka - potential breaking change + +The Exchange header constants in `KafkaConstants` used header values in the +lowercase / dotted `kafka.*` namespace, outside the `Camel` namespace, and were +therefore not filtered by the default `HeaderFilterStrategy` on upstream HTTP / +REST consumers. They have been renamed to follow the Camel naming convention +used across the rest of the component catalog. The Java field names are +unchanged; only the header string values have changed: + +[options="header"] +|=== +| Constant | Previous value | New value +| `KafkaConstants.PARTITION_KEY` | `kafka.PARTITION_KEY` | `CamelKafkaPartitionKey` +| `KafkaConstants.PARTITION` | `kafka.PARTITION` | `CamelKafkaPartition` +| `KafkaConstants.KEY` | `kafka.KEY` | `CamelKafkaKey` +| `KafkaConstants.TOPIC` | `kafka.TOPIC` | `CamelKafkaTopic` +| `KafkaConstants.OVERRIDE_TOPIC` | `kafka.OVERRIDE_TOPIC` | `CamelKafkaOverrideTopic` +| `KafkaConstants.OFFSET` | `kafka.OFFSET` | `CamelKafkaOffset` +| `KafkaConstants.HEADERS` | `kafka.HEADERS` | `CamelKafkaHeaders` +| `KafkaConstants.LAST_RECORD_BEFORE_COMMIT` | `kafka.LAST_RECORD_BEFORE_COMMIT` | `CamelKafkaLastRecordBeforeCommit` +| `KafkaConstants.LAST_POLL_RECORD` | `kafka.LAST_POLL_RECORD` | `CamelKafkaLastPollRecord` +| `KafkaConstants.TIMESTAMP` | `kafka.TIMESTAMP` | `CamelKafkaTimestamp` +| `KafkaConstants.OVERRIDE_TIMESTAMP` | `kafka.OVERRIDE_TIMESTAMP` | `CamelKafkaOverrideTimestamp` +| `KafkaConstants.KAFKA_RECORD_META` | `kafka.RECORD_META` | `CamelKafkaRecordMeta` +|=== + +`KafkaConstants.MANUAL_COMMIT` was already `Camel`-prefixed +(`CamelKafkaManualCommit`) and is unchanged. + +Routes that reference the constants symbolically (for example +`setHeader(KafkaConstants.OVERRIDE_TOPIC, ...)`) continue to work without +changes. Routes that set or read the headers by their literal string values +(for example `setHeader("kafka.OVERRIDE_TOPIC", ...)` or Simple expressions such +as `${headers[kafka.TOPIC]}`) must be updated to use the new values: + +[source,java] +---- +// before +from("platform-http:/api/events") + .setHeader("kafka.OVERRIDE_TOPIC", constant("events.topic")) + .to("kafka:default?brokers=localhost:9092"); + +// after +from("platform-http:/api/events") + .setHeader(KafkaConstants.OVERRIDE_TOPIC, constant("events.topic")) + .to("kafka:default?brokers=localhost:9092"); +---- + +The generated Endpoint DSL header accessors on `KafkaEndpointBuilderFactory` +keep their method names (`kafkaOverrideTopic()`, `kafkaTopic()`, +`kafkaPartitionKey()`, ...); only the returned string value reflects the new +`CamelKafka*` convention. + +==== Behaviour change: cross-transport propagation of kafka.* headers + +Because the renamed header values now begin with `Camel`, they are filtered by +the standard transport `HeaderFilterStrategy` (`HttpHeaderFilterStrategy`, +`JmsHeaderFilterStrategy`, etc.) when crossing a transport boundary, by design +— `Camel*` headers are framework-internal and are not propagated over the wire. + +Routes that bridge an external transport (HTTP, JMS, ...) into a `kafka:` +producer and let the sender choose the destination topic via the +`kafka.OVERRIDE_TOPIC` header must therefore carry that value in a +non-`Camel`-prefixed application header and map it to +`KafkaConstants.OVERRIDE_TOPIC` in the route between the transport `from` and +the `kafka:` `to`. Allowing untrusted senders to drive +`KafkaConstants.OVERRIDE_TOPIC` (which redirects the producer's target topic) +without such a mapping step is not the intended use of the component. diff --git a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_18.adoc b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_18.adoc index 9094e00eb0b55..0ffa575728cbe 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_18.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_18.adoc @@ -834,3 +834,72 @@ between the transport `from` and the `dns:` `to`. Allowing untrusted senders to drive `DnsConstants.DNS_SERVER` (the recursive resolver target in `dns:dig`) without such a mapping step is not the intended use of the component. + +=== camel-kafka - potential breaking change + +The Exchange header constants in `KafkaConstants` used header values in the +lowercase / dotted `kafka.*` namespace, outside the `Camel` namespace, and were +therefore not filtered by the default `HeaderFilterStrategy` on upstream HTTP / +REST consumers. They have been renamed to follow the Camel naming convention +used across the rest of the component catalog. The Java field names are +unchanged; only the header string values have changed: + +[options="header"] +|=== +| Constant | Previous value | New value +| `KafkaConstants.PARTITION_KEY` | `kafka.PARTITION_KEY` | `CamelKafkaPartitionKey` +| `KafkaConstants.PARTITION` | `kafka.PARTITION` | `CamelKafkaPartition` +| `KafkaConstants.KEY` | `kafka.KEY` | `CamelKafkaKey` +| `KafkaConstants.TOPIC` | `kafka.TOPIC` | `CamelKafkaTopic` +| `KafkaConstants.OVERRIDE_TOPIC` | `kafka.OVERRIDE_TOPIC` | `CamelKafkaOverrideTopic` +| `KafkaConstants.OFFSET` | `kafka.OFFSET` | `CamelKafkaOffset` +| `KafkaConstants.HEADERS` | `kafka.HEADERS` | `CamelKafkaHeaders` +| `KafkaConstants.LAST_RECORD_BEFORE_COMMIT` | `kafka.LAST_RECORD_BEFORE_COMMIT` | `CamelKafkaLastRecordBeforeCommit` +| `KafkaConstants.LAST_POLL_RECORD` | `kafka.LAST_POLL_RECORD` | `CamelKafkaLastPollRecord` +| `KafkaConstants.TIMESTAMP` | `kafka.TIMESTAMP` | `CamelKafkaTimestamp` +| `KafkaConstants.OVERRIDE_TIMESTAMP` | `kafka.OVERRIDE_TIMESTAMP` | `CamelKafkaOverrideTimestamp` +| `KafkaConstants.KAFKA_RECORD_META` | `kafka.RECORD_META` | `CamelKafkaRecordMeta` +|=== + +`KafkaConstants.MANUAL_COMMIT` was already `Camel`-prefixed +(`CamelKafkaManualCommit`) and is unchanged. + +Routes that reference the constants symbolically (for example +`setHeader(KafkaConstants.OVERRIDE_TOPIC, ...)`) continue to work without +changes. Routes that set or read the headers by their literal string values +(for example `setHeader("kafka.OVERRIDE_TOPIC", ...)` or Simple expressions such +as `${headers[kafka.TOPIC]}`) must be updated to use the new values: + +[source,java] +---- +// before +from("platform-http:/api/events") + .setHeader("kafka.OVERRIDE_TOPIC", constant("events.topic")) + .to("kafka:default?brokers=localhost:9092"); + +// after +from("platform-http:/api/events") + .setHeader(KafkaConstants.OVERRIDE_TOPIC, constant("events.topic")) + .to("kafka:default?brokers=localhost:9092"); +---- + +The generated Endpoint DSL header accessors on `KafkaEndpointBuilderFactory` +keep their method names (`kafkaOverrideTopic()`, `kafkaTopic()`, +`kafkaPartitionKey()`, ...); only the returned string value reflects the new +`CamelKafka*` convention. + +==== Behaviour change: cross-transport propagation of kafka.* headers + +Because the renamed header values now begin with `Camel`, they are filtered by +the standard transport `HeaderFilterStrategy` (`HttpHeaderFilterStrategy`, +`JmsHeaderFilterStrategy`, etc.) when crossing a transport boundary, by design +— `Camel*` headers are framework-internal and are not propagated over the wire. + +Routes that bridge an external transport (HTTP, JMS, ...) into a `kafka:` +producer and let the sender choose the destination topic via the +`kafka.OVERRIDE_TOPIC` header must therefore carry that value in a +non-`Camel`-prefixed application header and map it to +`KafkaConstants.OVERRIDE_TOPIC` in the route between the transport `from` and +the `kafka:` `to`. Allowing untrusted senders to drive +`KafkaConstants.OVERRIDE_TOPIC` (which redirects the producer's target topic) +without such a mapping step is not the intended use of the component.