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.

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