Apache Camel 4.x Upgrade Guide

The org.apache.camel.support.DefaultHeaderFilterStrategy changed default setting for lowercase from false to true.

JMS ObjectMessage support is now disabled by default. Java object serialization is a recurring source of security issues, and Camel JMS routes rarely use ObjectMessage in practice. The component will now refuse to create or read jakarta.jms.ObjectMessage instances unless the new objectMessageEnabled option is explicitly set to true.

This affects the following endpoint/component options that rely on ObjectMessage internally:

To restore the previous behavior, enable the option at the component or endpoint level:

Or, on a single endpoint:

The same default applies to camel-sjms (and camel-sjms2, which inherits from it): JMS ObjectMessage support is now disabled by default and gated by a new objectMessageEnabled option (default false) on SjmsComponent / SjmsEndpoint.

This affects the same endpoint/component options as camel-jms:

To restore the previous behavior, enable the option at the component or endpoint level:

Or, on a single endpoint:

The applyGuardrail producer operation now reads the guardrail identifier from a new dedicated header CamelAwsBedrockGuardrailIdentifier (constant BedrockConstants.GUARDRAIL_IDENTIFIER, typed String) instead of CamelAwsBedrockGuardrailConfig. The CamelAwsBedrockGuardrailConfig header is typed GuardrailConfiguration and is reserved for the converse and converseStream operations; the previous code path silently produced null whenever a route mixed converse and applyGuardrail calls. If you were not setting the guardrail identifier via header, the endpoint-level guardrailIdentifier option continues to work without changes.

Hazelcast instances created and managed by Camel (when no user-supplied Config or HazelcastInstance is provided) now apply a default JavaSerializationFilterConfig on the SerializationConfig of the Config built by Camel. The default whitelists the class name prefixes java., javax., org.apache.camel. and blacklists java.net..

This affects:

A user-supplied JavaSerializationFilterConfig (set on the SerializationConfig of a Config provided via hazelcastConfigUri, a referenced Config bean, or already wired into a pre-built HazelcastInstance) is respected and is not overwritten.

Applications that store classes outside the default whitelist on a Hazelcast topic, queue, map, list, set, or in one of the repositories above must provide their own Config with a JavaSerializationFilterConfig configured for their class names.

The Exchange header constants in JGroupsConstants 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:

This is a breaking change for routes that read or write these headers by their literal string value. Routes that reference the constant symbolically (for example setHeader(JGroupsConstants.HEADER_JGROUPS_DEST, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("JGROUPS_DEST", …​)) must be updated to use the new value (setHeader("CamelJGroupsDest", …​)).

The Exchange header values exposed by LuceneConstants have been renamed to follow the standard Camel naming convention. The field names are unchanged, so routes referencing the constants (LuceneConstants.HEADER_QUERY, LuceneConstants.HEADER_RETURN_LUCENE_DOCS) continue to work without modification. However, routes that set or read these headers using the raw string values must be updated:

As a consequence, the generated Endpoint DSL header accessors on LuceneHeaderNameBuilder have been renamed accordingly:

The Exchange header constants in JGroupsRaftConstants 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:

Routes that reference the constant symbolically (for example setHeader(JGroupsRaftConstants.HEADER_JGROUPSRAFT_SET_TIMEOUT, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("JGROUPSRAFT_SET_TIMEOUT", …​)) must be updated to use the new value (setHeader("CamelJGroupsRaftSetTimeout", …​)).

The Exchange header constants in ElasticSearchRestClientConstant 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:

Routes that reference the constant symbolically (for example setHeader(ElasticSearchRestClientConstant.SEARCH_QUERY, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("SEARCH_QUERY", …​)) must be updated to use the new value (setHeader("CamelElasticsearchSearchQuery", …​)).

When using the RETRIEVE_NODES or DELETE_NODE operations with the CamelNeo4jMatchProperties header, the property names provided in the JSON match map are now validated before the MATCH / DELETE WHERE clause is built. Property names must be valid identifiers matching [A-Za-z_][A-Za-z0-9_]*. A request whose match map contains a property name that does not match this pattern now fails fast with an IllegalArgumentException (wrapped in a Neo4jOperationException) instead of producing a malformed query. Property values continue to be passed as bound query parameters and are unaffected.

The SMTP producer no longer extracts dynamic JavaMail session properties from message headers by default. Previously any message header whose key started with mail.smtp. (or mail.smtps.) was applied to a per-message JavaMailSender, which meant an upstream producer that mapped untrusted input into the exchange header map (for example platform-http query parameters, JMS or Kafka messages from untrusted producers) could override transport-security settings such as mail.smtp.ssl.trust or mail.smtp.starttls.enable, or redirect the SMTP connection.

This behaviour is now disabled by default. Routes that legitimately rely on per-message mail.smtp. / mail.smtps. headers must opt back in on the endpoint:

Even with the opt-in, route authors should still strip the namespace with removeHeaders("mail.smtp.", "mail.smtps.") between any untrusted ingress and the mail producer.

In addition, the inbound MailHeaderFilterStrategy now blocks the mail.smtp. / mail.smtps. prefix as well, so an external mail message can no longer inject these into a downstream exchange.

The Exchange header constants in JiraConstants 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:

Routes that reference the constants symbolically (for example setHeader(JiraConstants.ISSUE_KEY, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("IssueKey", …​)) must be updated to use the new value (setHeader("CamelJiraIssueKey", …​)).

As a consequence, the generated Endpoint DSL header accessors on JiraHeaderNameBuilder have been renamed accordingly:

The Exchange header values exposed by GridFsConstants have been renamed to follow the standard Camel naming convention, bringing camel-mongodb-gridfs in line with the parent camel-mongodb component (MongoDbConstants.OPERATION_HEADER = "CamelMongoDbOperation"). The Java field names are unchanged, so routes referencing the constants symbolically (e.g. GridFsConstants.GRIDFS_OPERATION, GridFsConstants.GRIDFS_OBJECT_ID) continue to work without modification. However, routes that set or read these headers using the raw string values must be updated:

As a consequence, the generated Endpoint DSL header accessors on GridFsHeaderNameBuilder have been renamed accordingly:

The two Exchange header prefix constants in SolrConstants have been renamed to follow the Camel naming convention already used by the other constants in the same file (which were renamed in 4.10 under CAMEL-21697). The Java field names are unchanged; only the prefix string values have changed:

Routes that reference the constants symbolically (for example setHeader(SolrConstants.HEADER_FIELD_PREFIX + "id", …​)) continue to work without changes. Routes that set the headers by their literal string value (for example setHeader("SolrField.id", …​) or setHeader("SolrParam.commit", …​)) must be updated to use the new prefix (CamelSolrField.id, CamelSolrParam.commit).

Because the renamed prefixes now begin with Camel, they are stripped by the standard transport HeaderFilterStrategy (HttpHeaderFilterStrategy, 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 solr: producer and want to drive Solr document fields or query parameters from a header supplied by the sender must therefore carry the value in a non-Camel-prefixed application header and map it to the appropriate CamelSolrField. / CamelSolrParam. header in the route between the transport from and the solr: to.

The camel-test module has been removed from camel-bom. This module was included by mistake, as since Camel 4, this is not a JAR but a pom.xml file. Camel end users should use the camel-test-junit5 / camel-test-junit6 JARs and the others directly.

In the YAML DSL we have renamed routePolicy to routePolicyRef on the route node, as that is the correct name.

In the simple language then init blocks syntax has changed to require that each variable ends with a semicolon and new line (no trailing comments etc is allowed)

For example

Should be changed to have semicolons as shown below:

When configured a custom IdempotentRepository on camel-mail endpoint, then Camel will now auto-start the bean which is similar to what camel-file do as well.

The camel-json-patch is now deprecated - the library it uses is not active maintained and this module does not work with Jackon 3.

When using code first Rest DSL and have configured base.path then this will now be exclusively used for the returned server url in the API specification.

For example here we set base.path=cheese:

Then the generated API specification now returns:

Previously the context-path would always be used:

The intention is to allow to configure the base.path as is in the return API specification.

The simple language has deprecated binary operators that uses space in the name:

The org.apache.camel.component.file.GenericFileOperations has added method storeFileDirectly.

All not working metadata headers have been removed. The option extractAllMetadata has been removed. Using includeRawMetadata will have the same effect given that there is no more customMetadata available.

It corresponds to the removal of functionality no more working since 4.17. Given that this functionality was never available in a LTS version,that the next LST version is the next one and the fix requires important change in upstream dependency; it is not going through a deprecation phase and removed directly.

The class org.apache.camel.component.qdrant.Qdrant.Headers has been removed. It was deprecated since 4.15. It is replaced by org.apache.camel.component.qdrant.QdrantHeaders.

The upgrade of Tahu from 1.0.17 to 1.0.18 introduced an API break. HostApplicationEventHandler has been renamed to MultiHostApplicationEventHandler and introduced one more parameter on all methods.

Even if the interface HostApplicationEventHandler is public, I do not expect Camel users to use the implementation TahuHostApplicationEventHandler from Camel. Also the change would be relatively trivial. So replacing it without deprecating it first in order to be able to use the latest Tahu version right away.

Consequently, there is an API break org.apache.camel.tahu.handlers.TahuHostApplicationEventHandler has been removed. It is replaced by org.apache.camel.tahu.handlers.MultiTahuHostApplicationEventHandler.

When using Rest DSL in contract first style, then the HTTP engine (vertx-web) instead of a single router to handle all incoming Rest API calls, is now one unique router per API endpoint. This change can affect HTTP request validation as vertx/Quarkus is now also performing this per API endpoint according to the API specification.

All together this would make Camel behave similar for Rest DSL for both code first and contract first style.

The default headerFilterStrategy is now a new NatsHeaderFilterStrategy that filters headers starting with Camel / camel (case-insensitive) in both the inbound and outbound directions, aligning the component with the rest of the Camel component catalog (camel-kafka, camel-mail, camel-coap, camel-google-pubsub, …​). Routes that relied on passing through these header names from NATS messages can supply a custom headerFilterStrategy to restore the previous behaviour.

The default headerFilterStrategy is now a new XmppHeaderFilterStrategy that filters headers starting with Camel / camel (case-insensitive) in both the inbound and outbound directions, aligning the component with the rest of the Camel component catalog (camel-kafka, camel-mail, camel-coap, camel-google-pubsub, …​). Routes that relied on passing through these header names from XMPP messages can supply a custom headerFilterStrategy to restore the previous behaviour.

The camel-olingo2 and camel-olingo4 component are deprecated. This is due the Apache Olingo project is EOL and has been moved to the attic and is no longer maintained.

The vertx-websocket consumer now applies a HeaderFilterStrategy to the WebSocket query and path parameters before mapping them into the Camel message headers. The new default VertxWebsocketHeaderFilterStrategy filters headers starting with Camel / camel (case-insensitive) in both the inbound and outbound directions, aligning the component with the rest of the Camel component catalog (camel-coap, camel-kafka, camel-nats, …​). A new headerFilterStrategy endpoint option is available; routes that relied on receiving Camel-prefixed header names from WebSocket query or path parameters can supply a custom headerFilterStrategy to restore the previous behaviour.

The atmosphere-websocket consumer now applies the endpoint HeaderFilterStrategy to the WebSocket query parameters before mapping them into the Camel message headers. The inherited default HttpHeaderFilterStrategy filters headers starting with Camel / camel (case-insensitive). Routes that relied on receiving Camel-prefixed header names from WebSocket query parameters can supply a custom headerFilterStrategy to restore the previous behaviour.

The iggy consumer now applies a HeaderFilterStrategy to the Iggy message user-headers before mapping them into the Camel message headers. The new default IggyHeaderFilterStrategy filters headers starting with Camel / camel (case-insensitive) in both the inbound and outbound directions, aligning the component with the rest of the Camel component catalog. A new headerFilterStrategy endpoint option is available; routes that relied on receiving Camel-prefixed user-header names from Iggy messages can supply a custom headerFilterStrategy to restore the previous behaviour.

Sqs2HeaderFilterStrategy now also configures an inbound filter aligned with the existing outbound regex. Headers starting with Camel / camel (case-insensitive), breadcrumbId and org.apache.camel.* are now filtered in both the inbound and outbound directions, aligning the component with the rest of the Camel component catalog (camel-kafka, camel-mail, camel-coap, camel-google-pubsub, …​). Routes that relied on receiving these header names from inbound SQS messages can supply a custom headerFilterStrategy to restore the previous behaviour.

Sns2HeaderFilterStrategy now also configures an inbound filter aligned with the existing outbound regex. Headers starting with Camel / camel (case-insensitive), breadcrumbId and org.apache.camel.* are now filtered in both the inbound and outbound directions, aligning the component with the rest of the Camel component catalog. Routes that relied on receiving these header names on inbound SNS messages can supply a custom headerFilterStrategy to restore the previous behaviour.

The Exchange header constants in CxfConstants (module camel-cxf-common, shared by camel-cxf and camel-cxfrs) 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:

Routes that reference the constant symbolically (for example setHeader(CxfConstants.OPERATION_NAME, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("operationName", …​)) must be updated to use the new value (setHeader("CamelCxfOperationName", …​)).

In particular, the documented cxfrs SimpleConsumer dispatch idiom that routes on the operation name by its literal header name must be updated:

The Exchange header constants in DnsConstants 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:

Routes that reference the constant symbolically (for example setHeader(DnsConstants.DNS_SERVER, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("dns.server", …​) or setHeader("term", …​)) must be updated to use the new value: