IM 8.1.0 — Apache Camel 4.18 to 4.22 Migration

Apache Camel 4.18.2 → 4.22.0, crossing four releases: 4.19, 4.20, 4.21, 4.22.

This page covers only the changes that can affect a customer route, mapper or filter shipped on
IM. Changes to Camel components IM does not ship are omitted.

Camel 4.19 is the release that dropped Spring Boot 3 support. That is why IM 8.1.0 also moves to
Spring Boot 4 / Spring Framework 7 — the two upgrades cannot be separated.

Legend: DEPLOY-FAIL = route no longer deploys · RUNTIME = throws when the route runs ·
SILENT = route runs, behaviour differs.

1. High impact

1.1 camel-cxf: operationName header renamed — SILENT (4.21)

CxfConstants.OPERATION_NAME and OPERATION_NAMESPACE changed their header values:

<!-- BEFORE -->
<to uri="direct:${header.operationName}"/>

<!-- AFTER -->
<to uri="direct:${header.CamelCxfOperationName}"/>

There is a second-order effect: because the new names begin with Camel, the default
HeaderFilterStrategy now strips them at transport boundaries. If you bridge a SOAP operation
name over JMS or HTTP into a cxf: producer, carry it in a non-Camel-prefixed header and re-set
CamelCxfOperationName immediately before the cxf: endpoint.

Routes referencing the constant symbolically from Java/Groovy (CxfConstants.OPERATION_NAME) are
unaffected — only literal string references need changing.

1.2 camel-cxf: WS-Security is no longer on the classpath — RUNTIME (4.21)

Camel 4.21 made cxf-rt-ws-security an optional dependency of camel-cxf-soap. In IM 8.1.0 the
entire WS-Security / SAML stack is consequently absent from the runtime:
org.apache.wss4j:*, org.opensaml:*, org.apache.cxf:cxf-rt-ws-security, cxf-rt-security,
cxf-rt-security-saml, org.apache.santuario:xmlsec, net.shibboleth:*, org.cryptacular.

Who is affected. Any customer SOAP web service configured with WS-Security — UsernameToken,
message signing, encryption, or SAML assertions. IM itself never used these libraries, so nothing in
the product regresses; the risk is entirely for customer-supplied CXF configuration that relied on
them being present transitively.

Detection. ClassNotFoundException / NoClassDefFoundError at route startup or on first
message, naming a org.apache.wss4j or org.opensaml class.

Action. If you use WS-Security, raise a ticket — the dependency must be added back explicitly to
the IM image. Please do this before upgrading if you know you rely on it.

1.3 camel-mail: header-driven recipients now require opt-in — SILENT (4.21)

Camel 4.21 made camel-mail secure by default. Setting To, From, Subject or Reply-To through
message headers is ignored unless explicitly enabled:

<!-- BEFORE: header was honoured -->
<setHeader name="To"><constant>ops@example.com</constant></setHeader>
<to uri="smtp://mail.example.com"/>

<!-- AFTER: opt in explicitly -->
<to uri="smtp://mail.example.com?useHeaderRecipients=true"/>

Options: useHeaderRecipients, useHeaderFrom, useHeaderSubject, useHeaderReplyTo — all default
false.

This is silent: the mail is still sent, to whatever the endpoint URI configures, so a
header-addressed notification quietly goes to the wrong place (or nowhere).

The consumer-side dispatch headers were also renamed: copyTo → CamelMailCopyTo,
moveTo → CamelMailMoveTo, delete → CamelMailDelete. RFC 5322 header constants such as
Subject are unchanged.

1.4 toD / enrich no longer resolve {{...}} at runtime — SILENT (4.22)

Property placeholders are resolved only in the static route template, not in a URI computed
per-message.

<!-- If the header value contains {{...}}, it is now treated as literal text -->
<toD uri="${header.targetEndpoint}"/>

recipientList, routingSlip and dynamicRouter are unaffected. pollEnrich still resolves at
runtime for now.

2. Medium impact

2.1 camel-xslt-saxon: secure processing always on — RUNTIME (4.22)

secureProcessing (default true) is now applied unconditionally. Previously it was only set when
saxonExtensionFunctions was configured, so the default configuration effectively ran without
secure processing. External DTD and stylesheet access is blocked.

Affected. XSLT that calls Java extension functions, or that resolves an external DTD/stylesheet.
Fix. Set secureProcessing=false explicitly on the endpoint if you need extension functions.

2.2 camel-zipfile / tarfile: CamelFileName is now the base name — SILENT (4.22)

On unmarshal and split, CamelFileName is stripped to the entry's base name (Zip-Slip protection).
Routes that reconstructed directory structure from that header now write everything flat.

Fix. Use zipFileName (zip) or CamelTarFileEntryName (tar) for the full path.

2.3 camel-file / camel-ftp: preSort changed type — CHANGED SYNTAX (4.22)

preSort moved from boolean to String, accepting name, modified, size and the descending
forms -name, -modified, -size. true still works as an alias for name, so existing routes
keep working — but you can now be explicit.

2.4 camel-ftp: localWorkDirectory path-traversal hardening — RUNTIME (4.21)

A remote filename containing ../ can no longer resolve outside the local work directory; it throws
GenericFileOperationFailedException. Legitimate transfers are unaffected.

2.5 camel-aws2-s3: listObjects uses ListObjectsV2 — RUNTIME (4.19)

Only affects pojoRequest=true: ListObjectsRequest/ListObjectsResponse must become
ListObjectsV2Request/ListObjectsV2Response. Header-based usage is unchanged.

2.6 camel-jsonpath: writeAsString fix — SILENT (4.22)

A JsonPath expression evaluating to a JSON object (e.g. $.args) now serialises to a JSON string
instead of a Map with individually stringified values. If you relied on the old (buggy) shape, use
a wildcard form such as $.content.*.

2.7 camel-spring-rabbitmq: default changes — SILENT (4.22)

• Component-level replyTimeout default corrected from 5 s to 30 s (it had been wrongly
  overriding the documented endpoint default).

• Auto-declared queues are now durable=true by default, aligning with RabbitMQ 4.3+.
  Restore with arg.queue.durable=false&arg.queue.exclusive=true.

2.8 camel-openapi-java: base.path wins — SILENT (4.19)

When base.path is configured on a code-first Rest DSL, it is now used exclusively for the generated
server URL; previously the context path always won.

3. Lower impact / awareness

3.1 Simple language

• floor and ceil return long instead of int (no more silent overflow above Integer.MAX_VALUE).

• The $init{...}init$ block requires each statement to end with a semicolon and newline; trailing
  comments are not allowed.

• csimple (compiled simple) is deprecated — migrate to simple.

3.2 Removed components — DEPLOY-FAIL (4.19, 4.21)

camel-cloud and the serviceCall EIP, camel-service, camel-google-pubsub-lite, camel-stomp,
camel-aws-xray, camel-guava-eventbus, camel-grape, camel-elytron, camel-github. A route
referencing these fails to deploy.

3.3 Multicast honours UseOriginalAggregationStrategy — SILENT (4.22)

Previously silently ineffective; an aggregated result could overwrite the original body on error.
Routes relying on the broken behaviour change outcome.

3.4 Java deserialization filters tightened (4.21)

Applies to the opt-in allowJavaSerializedObject / transferException paths on camel-http,
camel-jetty, camel-servlet, and to camel-sql's JdbcAggregationRepository. The default filter
denies java.net.** and enforces JEP-290 graph limits. Override via deserializationFilter or
-Djdk.serialFilter if you legitimately transfer such payloads.

3.5 camel-sql aggregation repository (4.22)

remove() now throws OptimisticLockingException on a stale version instead of silently succeeding.
A long-standing PostgreSQL insert bug is fixed (requires the version BIGINT column). Schema-qualified
table names (myschema.aggregation) are now accepted.

3.6 Monitoring

• camel-micrometer: the routeId tag is now always present, using an empty string when
  unavailable (previously the tag was absent). Dashboards matching on label absence need updating.

• JMX Throughput is now an EWMA-smoothed value rather than an instantaneous rate.

3.7 camel-spring-boot property types (4.22)

camel.routecontroller.* and camel.startupcondition.* timing properties are bound as
java.time.Duration. Plain numbers are still read as milliseconds, and duration strings (5s, 2m)
are now accepted too — backward compatible.

4. Search patterns for your routes

5. Sources

Official Apache Camel upgrade guides:
4.19 ·
4.20 ·
4.21 ·
4.22