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:

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 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", …​)).

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 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", …​)).

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. 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.* headers must opt back in on the endpoint:

Even with the opt-in, route authors should still strip the namespace with removeHeaders("mail.smtp.*") 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:

Two Exchange header constants in ArangoDbConstants that were not in the Camel namespace (and therefore not filtered by the default HeaderFilterStrategy) have been renamed to follow the Camel naming convention. The Java field names are unchanged; only the header string values have changed:

The remaining constants (MULTI_UPDATE, MULTI_INSERT, MULTI_DELETE, AQL_QUERY, AQL_QUERY_BIND_PARAMETERS, AQL_QUERY_OPTIONS) were already Camel-prefixed and are unchanged.

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

As a consequence, the generated Endpoint DSL header accessors on ArangoDbHeaderNameBuilder have been renamed: key() → arangoDbKey() and resultClassType() → arangoDbResultClassType().

The three Exchange header constants in ShiroSecurityConstants that drive Shiro authentication used header values outside the Camel namespace (SHIRO_SECURITY_TOKEN, SHIRO_SECURITY_USERNAME, SHIRO_SECURITY_PASSWORD) and were therefore not filtered by the default HeaderFilterStrategy. They have been renamed to follow the Camel naming convention. The Java field names are unchanged; only the header string values have changed:

These headers carry credentials and a serialized authentication token, so filtering them at transport boundaries by default is particularly important.

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

Because the three header values are now in the Camel* namespace, transports that filter Camel-internal headers by default (JMS, CXF, HTTP, etc.) will strip the serialized Shiro authentication token before publishing. This is the intended behavior for untrusted producers. Trusted Shiro-over-transport routes that previously relied on the token surviving the boundary must opt those three headers back in via a custom HeaderFilterStrategy, for example:

A worked example is in ShiroOverJmsTest in the camel-itest module.

The Exchange header constants in PdfHeaderConstants 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(PdfHeaderConstants.PDF_DOCUMENT_HEADER_NAME, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("pdf-document", …​)) must be updated to use the new value (setHeader("CamelPdfDocument", …​)).

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

The two Exchange header constants in Jt400Constants that were not in the Camel namespace (and therefore not filtered by the default HeaderFilterStrategy) have been renamed to follow the Camel naming convention. The Java field names are unchanged; only the header string values have changed:

Jt400Constants.KEY is the data-queue key used for keyed-data-queue read and write operations. The remaining constants (MESSAGE, MESSAGE_ID, MESSAGE_FILE, MESSAGE_TYPE, MESSAGE_SEVERITY, MESSAGE_DFT_RPY, MESSAGE_REPLYTO_KEY) were already Camel-prefixed and are unchanged.

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

As a consequence, the generated Endpoint DSL header accessors on Jt400HeaderNameBuilder have been renamed: kEY() → jt400Key() and senderInformation() → jt400SenderInformation().

The consumer-side dispatch header constants in MailConstants that control post-processing of a consumed mail message used header values outside the Camel namespace (copyTo, moveTo, delete) and were therefore not filtered by the default HeaderFilterStrategy. They have been renamed to follow the Camel naming convention (companion to the CAMEL-23522 mail.smtp.* hardening). The Java field names are unchanged; only the header string values have changed:

The standard RFC 5322 message header constants (MAIL_SUBJECT = Subject, MAIL_FROM = From, MAIL_TO = To, MAIL_CC = Cc, MAIL_BCC = Bcc, MAIL_REPLY_TO = Reply-To, MAIL_CONTENT_TYPE = contentType) are unchanged, as they map directly to the corresponding email fields and renaming them would break mail interoperability.

The equally-named copyTo and moveTo endpoint URI options on the mail consumer are also unchanged; only the Exchange header values are affected.

Routes that reference the constants symbolically (for example setHeader(MailConstants.MAIL_DELETE, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("delete", true)) must be updated to use the new value (setHeader("CamelMailDelete", true)).

As a consequence, the generated Endpoint DSL header accessors on MailHeaderNameBuilder have been renamed: copyTo() → mailCopyTo(), moveTo() → mailMoveTo(), and delete() → mailDelete().

The Exchange header constants in Web3jConstants 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(Web3jConstants.FROM_ADDRESS, …​)) continue to work without changes. Routes that set the header by its literal string value (for example setHeader("FROM_ADDRESS", …​)) must be updated to use the new value (setHeader("CamelWeb3jFromAddress", …​)).

The Web3jConstants.ETH_HASHRATE constant is dual-purpose: it is both the CamelWeb3jOperation value that dispatches the ethHashrate RPC and the header name read by the ETH_SUBMIT_HASHRATE operation. Routes that referenced the literal string "ETH_HASHRATE" (in either role) must be updated to "CamelWeb3jEthHashrate". Routes using the symbolic constant reference are unaffected. The other producer-dispatch operation identifiers (WEB3_CLIENT_VERSION, ETH_GAS_PRICE, ETH_SEND_TRANSACTION, …​) keep their previous string values because they are operation enum values rather than Exchange header names.

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

A new accessor web3jOperation() is also generated for Web3jConstants.OPERATION (the producer dispatch header). This constant did not appear in the catalog previously, so no DSL accessor renaming applies to it.

The Exchange header constants in ElasticsearchConstants and OpensearchConstants 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.

ElasticsearchConstants:

OpensearchConstants:

ElasticsearchConstants.PROPERTY_SCROLL_ES_QUERY_COUNT and OpensearchConstants.PROPERTY_SCROLL_OPENSEARCH_QUERY_COUNT were already Camel-prefixed (CamelElasticsearchScrollQueryCount / CamelOpenSearchScrollQueryCount) and are unchanged.

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

The generated Endpoint DSL header accessors on ElasticsearchHeaderNameBuilder and OpensearchHeaderNameBuilder have been renamed accordingly (operation() → elasticsearchOperation() / opensearchOperation(), indexId() → elasticsearchIndexId() / opensearchIndexId(), etc.).

The Exchange header constants in these Google Cloud components carried a GoogleCloud<Service> / GoogleSecretManager prefix that is not in the Camel namespace, so the default HeaderFilterStrategy did not filter them at transport boundaries. They have been renamed to add the Camel prefix. The Java field names are unchanged; only the header string values have changed:

The GoogleSecretManagerConstants.SECRET_ID, VERSION_ID and REPLICATION constants were already Camel-prefixed (CamelGoogleSecretManagerSecretId, etc.) and are unchanged.

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

The generated Endpoint DSL header accessor names are unchanged (for example googleCloudFunctionsOperation()), since the Camel prefix is stripped when deriving the accessor name; the accessors now return the new Camel-prefixed values.

The Exchange header constants in OpenstackConstants, KeystoneConstants, NovaConstants, CinderConstants, GlanceConstants, NeutronConstants, and SwiftConstants 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.

Common constants (in OpenstackConstants):

Keystone (KeystoneConstants):

Nova (NovaConstants):

Cinder (CinderConstants):

Glance (GlanceConstants):

Neutron (NeutronConstants):

Swift (SwiftConstants):

SwiftConstants.CONTAINER_METADATA_PREFIX, SwiftConstants.VERSIONS_LOCATION, SwiftConstants.CONTAINER_READ, and SwiftConstants.CONTAINER_WRITE intentionally keep their previous values (X-Container-Meta-, X-Versions-Location, X-Container-Read, X-Container-Write) because they are part of the Swift HTTP protocol contract used by openstack4j to forward container metadata and ACLs to the Swift backend. Renaming them would break interoperability with the Swift API.

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

The generated Endpoint DSL header accessors on each component’s HeaderNameBuilder are renamed accordingly (operation() → openstackOperation(), password() → openstackKeystonePassword(), adminPassword() → openstackNovaAdminPassword(), etc.).

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.

Upgraded to Tika v3, and removed textMain from tikaParseOutputFormat option.

The kamelet component is now parsing endpoint parameters using raw mode to ensure when using sensitive parameters such as access keys, passwords etc. they are not URI encoded.

The org.apache.camel.spi.ExecutorServiceManager.ThreadFactoryListener has changed the method signature to include the source, so the method is changed from ThreadFactory onNewThreadFactory(ThreadFactory factory) to ThreadFactory onNewThreadFactory(Object source, ThreadFactory factory)

The HTTP server for standalone camel-main applications has separated management services and business services. This means that configurations in application.properties should be changed from camel.server.xxx to camel.management.xxx as shown below:

The default HTTP endpoints has changed in some management services as listed below:

The camel-jbang has upgraded to Java 21 as the default java-version when running and exporting. To keep using java 17, you can use --java-version=17 as parameter.

The camel export will not include camel-observabilities-services out of the box. To include this, then use --observe to enable this during export.

Notice when exporting to kubernetes then camel-observabilities-services is always enabled.

When controlling Camel JBang exports with configuration in application.properties then there was a duplicate option (camel.jbang.repositories and camel.jbang.repos) which has been fixed to be only camel.jbang.repos.

The scopes parameter for camel-google-calendar, camel-google-calendar-streams, camel-google-drive, camel-google-mail, camel-google-mail-streams and camel-google-sheets-streams has been defined as String instead of Collection<String>. For the migration users will need to, eventually, define scopes as a comma separated list of scopes instead of a Collection instance. For more information the related issue is CAMEL-22247.

The nodeMeta and the tags parameter for camel-consul has been defined as String instead of List<String>. For the migration users will need to, eventually, define nodeMeta as a comma separated list of nodeMeta instead of a List or Set instance. For more information the related issue is CAMEL-17339.

The configKeys parameter for camel-dapr has been defined as String instead of List<String>. For the migration users will need to, eventually, define configKeys as a comma separated list of config Keys instead of a List instance. For more information the related issue is CAMEL-17339.

The availableZones parameter for camel-huawei-dms has been defined as String instead of List<String>. For the migration users will need to, eventually, define availableZones as a comma separated list of available zones instead of a List instance. For more information the related issue is CAMEL-17339.

The ids parameter for camel-weather has been defined as String instead of List<String>. For the migration users will need to, eventually, define ids as a comma separated list of id instead of a List instance. For more information the related issue is CAMEL-17339.

The addresses, privateFor and Topics parameters for camel-web3j have been defined as String instead of List<String>. For the migration users will need to, eventually, define addresses, privateFor or topics as a comma separated list of addresses, privateFor or topics instead of a List instance. For more information the related issue is CAMEL-17339.

The jobLauncher and jobRegistry is now autowired on the component if there is a single instance pre-configured in the application. This avoids having to wire this into the Camel component or endpoints.

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 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.

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 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 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:

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:

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:

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.