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 toorg.apache.camel.support.scan.DefaultPackageScanClassResolver
-
org.apache.camel.impl.engine.DefaultPackageScanResourceResolver
is moved toorg.apache.camel.support.scan.DefaultPackageScanResourceResolver
-
org.apache.camel.impl.engine.WebSpherePackageScanClassResolver
is moved toorg.apache.camel.support.scan.WebSpherePackageScanClassResolver
-
org.apache.camel.impl.scan.AnnotatedWithAnyPackageScanFilter
is moved toorg.apache.camel.support.scan.AnnotatedWithAnyPackageScanFilter
-
org.apache.camel.impl.scan.AnnotatedWithPackageScanFilter
is moved toorg.apache.camel.support.scan.AnnotatedWithPackageScanFilter
-
org.apache.camel.impl.scan.AssignableToPackageScanFilter
is moved toorg.apache.camel.support.scan.AssignableToPackageScanFilter
-
org.apache.camel.impl.scan.CompositePackageScanFilter
is moved toorg.apache.camel.support.scan.CompositePackageScanFilter
-
org.apache.camel.impl.scan.InvertingPackageScanFilter
is moved toorg.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.
Removed the Exchange.BEAN_METHOD_NAME
constant as it has been deprecated and are not in use.
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.
Rest DSL
When setting the context-path in rest configuration then this now takes precedence over the base-path defined in an openapi specification when using rest dsl contract-first.
For example
- restConfiguration:
clientRequestValidation: true
contextPath: /cheese
- rest:
openApi:
specification: petstore-v3.json
Then Camel will now use /cheese
as the base-path for the Rest DSL API endpoints from the petstore-v3.json
openapi specification file.
When using code-first with Rest DSL and are specifying security constraints, then bearer
in YAML and XML DSL has been renamed to bearerToken
to be aligned with Java DSL.
For example:
<rest path="/user" description="User rest service" consumes="application/json" produces="application/json">
<securityDefinitions>
<bearer key="myBearerKey" description="Bearer token for security"/>
</securityDefinitions>
...
</rest>
Should be changed as follows:
<rest path="/user" description="User rest service" consumes="application/json" produces="application/json">
<securityDefinitions>
<bearerToken key="myBearerKey" description="Bearer token for security"/>
</securityDefinitions>
...
</rest>
XML-IO DSL
The camel-xml-io
now has its own XSD Schema using the namespace: http://camel.apache.org/schema/xml-io
. This means that when using camel-xml-io
to dump route models, then they now use http://camel.apache.org/schema/xml-io
instead of http://camel.apache.org/schema/spring
.
It is also recommended to migrate your XML-IO XML files to use the new namespace instead of the legacy Spring XSD.
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-jbang
The camel cmd send
command now sends the message without the need for any existing running Camel integration. To use any existing integration then specify the integration name or PID.
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
.
camel-smb
The path
option is now configured in the context-path instead of query parameter. This makes the endpoint more similar to other file based components.
Before:
smb://mysmbserver/myshare/?path=mypath
After:
smb://mysmbserver/myshare/mypath
The path can still be specified in the URI as backwards compatible. |
camel-spring-boot
Upgraded to Spring Boot 3.5.0.
The camel-servetl-starter
has a minor code change for the Spring Boot 3.5 upgrade.
The camel-jetty-starter
has been deprecated in favor of camel-platform-http-starter
to use the HTTP server from Spring Boot.
The camel-undertow-starter
has been deprecated in favor of camel-platform-http-starter
to use the HTTP server from Spring Boot.