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.

Upgrading Camel 4.11 to 4.12

camel-core

The package scan classes has moved from camel-base-engine to camel-support JAR and moved to a new package:

  • org.apache.camel.impl.engine.DefaultPackageScanClassResolver is moved to org.apache.camel.support.scan.DefaultPackageScanClassResolver

  • org.apache.camel.impl.engine.DefaultPackageScanResourceResolver is moved to org.apache.camel.support.scan.DefaultPackageScanResourceResolver

  • org.apache.camel.impl.engine.WebSpherePackageScanClassResolver is moved to org.apache.camel.support.scan.WebSpherePackageScanClassResolver

  • org.apache.camel.impl.scan.AnnotatedWithAnyPackageScanFilter is moved to org.apache.camel.support.scan.AnnotatedWithAnyPackageScanFilter

  • org.apache.camel.impl.scan.AnnotatedWithPackageScanFilter is moved to org.apache.camel.support.scan.AnnotatedWithPackageScanFilter

  • org.apache.camel.impl.scan.AssignableToPackageScanFilter is moved to org.apache.camel.support.scan.AssignableToPackageScanFilter

  • org.apache.camel.impl.scan.CompositePackageScanFilter is moved to org.apache.camel.support.scan.CompositePackageScanFilter

  • org.apache.camel.impl.scan.InvertingPackageScanFilter is moved to org.apache.camel.support.scan.InvertingPackageScanFilter

The ExchangeHelper.copyResults has been improved to also copy over exchange variables from the source to the target.

Removed unused Johnzon in org.apache.camel.model.dataformat.JsonLibrary enum as camel-johnzon is not supported in Camel v4. This removal also means johnzon was removed from XSD and YAML DSL schemas.

Header Filter Strategy

The default HeaderFilterStrategy has changed to be case-insensitive by default. This ensures that headers sent over transports will be filtered also if they use different cases such as camelKey and CAMELKEY, camelkey would all be considered the same key and filtered.

The default HeaderFilterStrategy has also removed filtering of keys starting with the legacy Camel v1 syntax org.apache.camel.. Camel v2 onwards are using the Camel…​ key standard.

Propagating variables in EIPs in seda/kamelet components

The kamelet and seda component and EIPs such as Split, Multicast, Recipient List, Enrich, PollEnrich, Loop (copy mode) will now also propagate exchange variables as well into the result (i.e. exchange properties and message headers is already being propagated).

Type Converters

Using type converters that has been marked to allow null via (@Converter(allow-null = true)) has been improved to allow returning null as a positive answer when using convertBodyTo EIP and mandatoryConvertTo or getMandatoryBody etc.

This behavior was present in Camel v2 and some internal optimization in Camel v3 had changed this to not be the case. Using type converters that can return null is a rare use-case, and it’s not a good practice.

Java DSL

When using Choice EIP then in some situations you may need to use .endChoice() to be able to either continue added more nodes to the current Choice EIP, or that you are working with nested Choice EIPs (choice inside choice), then you may also need to use endChoice to go back to the parent choice to continue from there.

However, there has been some regressions from upgrading older Camel releases to 4.11, and therefore we have refactored endChoice to work more consistent.

For example the following code

from("direct:start")
    .choice()
        .when(header("foo").isGreaterThan(1))
            .choice()
                .when(header("foo").isGreaterThan(5))
                    .to("mock:big")
                .otherwise()
                    .to("mock:med")
            .endChoice()
        .otherwise()
            .to("mock:low")
        .end();

Should now be

from("direct:start")
    .choice()
        .when(header("foo").isGreaterThan(1))
            .choice()
                .when(header("foo").isGreaterThan(5))
                    .to("mock:big")
                .otherwise()
                    .to("mock:med")
            .end().endChoice()
        .otherwise()
            .to("mock:low")
        .end();

Notice that the endChoice is changed to end().endChoice(). This is required to be consistent to end the current choice (inner) and then afterwards change the scope to be Choice EIP to be able to continue in the outer Choice. Otherwise the Java DSL cannot know the scope is Choice EIP and you would not be able to add the otherwise block to the outer Choice.

camel-as2

Add options allowing the addition of an Authorization header for Basic or Bearer authentication to client and asynchronous MDN requests.

camel-jackson / camel-jacksonxml

The default unmarshalType has been changed from HashMap to LinkedHashMap that keeps ordering of the elements so they have similar order as the input document.

camel-micrometer

The tags parameter has been fixed to be multivalued and tooling friendly. So instead of configuring tags=a=1&b=2 then this should be configured as tags.a=1&tags.b=2 and so forth.

camel-main

We have introduced the possibility to use a management server where to expose management endpoints (such as health, metrics, etcetera). The new server will be available by default on port 9876. This and other several configuration can be changed using camel.management application properties group. In order to avoid breaking compatibility, the previous services running on business port (default 8080) will be still running on the old port AND on the new port for a few future releases. However, you’re invited to move your configuration and adopt the new camel.management embedded server for management services as soon as possible.

camel-observability-services

As seen in camel-main change, the component is now adopting the new management port to expose its services. However, it will be still possible to use also the old port to avoid introducing any breaking compatibility. Mind that this possibility will be removed in future versions.

camel-microprofile-fault-tolerance

Some options on the faultToleranceConfiguration DSL have been removed:

  • bulkheadExecutorService

  • timeoutScheduledExecutorService

They are replaced with a new option threadOffloadExecutorService as a general purpose custom ExecutorService for fault tolerance thread offloading.

Similarly, there is now only a single camel-main configuration option for the fault tolerance ExecutorService named camel.faulttolerance.threadOffloadExecutorService.

faultToleranceConfiguration option circuitBreaker is replaced by typedGuard and it’s camel-main configuration option is camel.main.faulttolerance.typedGuard.

Back to top