Apache Camel 4.x Upgrade Guide

This document is for helping you upgrade your Apache Camel application from Camel 4.x to 4.y. For example, if you are upgrading Camel 4.0 to 4.2, then you should follow the guides from both 4.0 to 4.1 and 4.1 to 4.2.

The Camel Upgrade Recipes project provides automated assistance for some common migration tasks. Note that manual migration is still required. See the documentation page for details.

Upgrading Camel 4.1 to 4.2

camel-api

Added boolean parameter to matchProcess method on org.apache.camel.spi.Condition.

camel-base-engine

The class org.apache.camel.impl.DebuggerBacklogDebugger has been refactored to an interface org.apache.camel.spi.BacklogDebugger and a default implementation org.apache.camel.impl.debugger.DefaultBacklogDebugger.

camel-main

The option camel.main.debugger has been renamed to camel.debug.enabled.

camel-management-api

The org.apache.camel.api.management.mbean.ManagedBacklogDebuggerMBean.dumpTracedMessagesAsXml(String, boolean) has been deprecated. The second parameter is ignored with default implementation.

To continue to have access to exchange properties, call setIncludeExchangeProperties(true) before messages are sent to have access to exchange properties.

camel-file

The readLock=changed with using readLockMinAge has been restored to same behaviour as 3.x.

For example, using readLockMinAge=5s would pick up files that are older than 5 seconds from startup time. If you have many existing files on startup that are old, then Camel will now again be fast, and pick up these files immediately.

camel-kafka

The consumer will now pre-validate hostname:port and DNS resolution on startup, and fail-fast in case of mis-configuration or invalid hostname.

This can be disabled by setting preValidateHostAndPort=false, which will postpone validation to consumer is started, and will instead re-connect endlessly (5 sec delay by default) until success.

camel-observation / camel-opentelemetry

The excludePatterns option has changed from Set<String> to be String where multiple patterns are separated by comma. This is more configuration and tooling friendly and used by other components.

camel-saga, camel-lra

The org.apache.camel.service.lra.LRAClient can now access Exchange to retrieve further context information. Therefore, there are following changes in interface methods - org.apache.camel.saga.CamelSagaService.compensate() changed to org.apache.camel.saga.CamelSagaService.compensate(Exchange exchange) - org.apache.camel.saga.CamelSagaService.complete() changed to org.apache.camel.saga.CamelSagaService.complete(Exchange exchange) - org.apache.camel.saga.CamelSagaCoordinator.newSaga is now org.apache.camel.saga.CamelSagaCoordinator.newSaga(Exchange exchange) to support the transport of Exchange.

As a result of interface changes, also the known implementation classes and usages have been adopted.

camel-ignite

The Apache Ignite project (v2.15) is not yet Java 21 compatible and therefore camel-ignite is not expected to function correctly if using Java 21.

A new release of Apache Ignite is expected that will start to support Java 21.

camel-dynamic-router EIP component (non-core)

The Dynamic Router EIP component has been refactored to use the Multicast Processor for sending messages to recipients, and this brought some additional configuration options:

parallelProcessing, parallelAggregate, stopOnException, ignoreInvalidEndpoints, streaming, timeout, onPrepare, shareUnitOfWork, executorService, and aggregationStrategy. These configuration items are for configuring the Multicast Processor within the Dynamic Router EIP component, so their description, meaning, and effect are identical to that of the Multicast Processor.

When upgrading to this version, you should still be able to use this component with the configuration from previous versions. The new options allow more specific configuration if you need it.

camel-spring & camel-spring-boot

Autowiring Primary beans

Camel will now take into account @Primary beans from Spring when autowiring by type. For example, a JDBC DataSource in the SQL component will now use the @Primary data source when multiple data sources are defined.

Previously, Camel would not autowire if there are two or more beans for a given type.

This is a change in behaviour, that can affect your applications when upgrading.

Properties

The initialProperties and overrideProperties on Camel PropertiesComponent will now take precedence over Spring Boot properties. This can be used for testing purpose, to allow overriding properties when using CamelTestSupport for unit testing.