Apache Camel 3.x to 4.0 Migration Guide
This document is intended to help you migrate your Apache Camel applications from version 3.20 or higher to 4.0. If you are upgrading from an older Camel 3.x release, such as 3.14, then make sure to read the individual Camel 3.x Upgrade Guide to upgrade to the 3.20 release, prior to upgrade to Camel 4.
If you are upgrading Camel 4.x to 4.y then use the Camel 4.x Upgrade Guide. |
Removed Components
The following components has been removed:
Component | Alternative component(s) |
---|---|
camel-activemq | camel-jms, camel-sjms, camel-amqp |
camel-any23 | none |
camel-atmos | none |
camel-caffeine-lrucache | camel-cache, camel-ignite, camel-infinispan |
camel-cdi | camel-spring-boot, camel-quarkus |
camel-directvm | camel-direct |
camel-dozer | camel-mapstruct |
camel-elasticsearch-rest | camel-elasticsearch |
camel-gora | none |
camel-hbase | none |
camel-iota | none |
camel-ipfs | none |
camel-jbpm | none |
camel-jclouds | none |
camel-johnzon | camel-jackson, camel-fastjson, camel-gson |
camel-microprofile-metrics | camel-micrometer, camel-opentelemetry |
camel-milo | none |
camel-opentracing | camel-micrometer, camel-opentelemetry |
camel-rabbitmq | spring-rabbitmq-component |
camel-rest-swagger | camel-openapi-rest |
camel-restdsl-swagger-plugin | camel-restdsl-openapi-plugin |
camel-resteasy | camel-cxf, camel-rest |
camel-solr | none |
camel-spark | none |
camel-spring-integration | none |
camel-swagger-java | camel-openapi-java |
camel-websocket | camel-vertx-websocket |
camel-websocket-jsr356 | camel-vertx-websocket |
camel-vertx-kafka | camel-kafka |
camel-vm | camel-seda |
camel-xstream | camel-jacksonxml |
camel-zipkin | camel-micrometer, camel-opentelemetry |
JUnit 4
All the camel-test
modules that were JUnit 4.x based has been removed. All test modules now use JUnit 5.
API Changes
We have removed deprecated APIs such as the following:
-
The
org.apache.camel.ExchangePattern
has removedInOptionalOut
. -
Removed
getEndpointMap()
method fromCamelContext
. -
Removed
@FallbackConverter
as you should use@Converter(fallback = true)
instead. -
Removed
uri
attribute on@EndpointInject
,@Produce
, and@Consume
as you should usevalue
(default) instead. For example@Produce(uri = "kafka:cheese")
should be changed to@Produce("kafka:cheese")
-
Removed
label
on@UriEndpoint
as you should usecategory
instead. -
Removed all
asyncCallback
methods onProducerTemplate
. UseasyncSend
orasyncRequest
instead. -
Removed
org.apache.camel.spi.OnCamelContextStart
. Useorg.apache.camel.spi.OnCamelContextStarting
instead. -
Removed
org.apache.camel.spi.OnCamelContextStop
. Useorg.apache.camel.spi.OnCamelContextStopping
instead. -
Decoupled the
org.apache.camel.ExtendedCamelContext
from theorg.apache.camel.CamelContext
. -
Replaced
adapt()
fromorg.apache.camel.CamelContext
withgetCamelContextExtension
-
Decoupled the
org.apache.camel.ExtendedExchange
from theorg.apache.camel.Exchange
. -
Replaced
adapt()
fromorg.apache.camel.ExtendedExchange
withgetExchangeExtension
-
Exchange failure handling status has moved from being a property defined as
ExchangePropertyKey.FAILURE_HANDLED
to a member of the ExtendedExchange, accessible via `isFailureHandled()`method. -
Removed
Discard
andDiscardOldest
fromorg.apache.camel.util.concurrent.ThreadPoolRejectedPolicy
. -
Removed
org.apache.camel.builder.SimpleBuilder
. Was mostly used internally in Camel with the Java DSL in some situations. -
Moved
org.apache.camel.support.IntrospectionSupport
tocamel-core-engine
for internal use only. End users should useorg.apache.camel.spi.BeanInspection
instead. -
Removed
archetypeCatalogAsXml
method fromorg.apache.camel.catalog.CamelCatalog
. -
The
org.apache.camel.health.HealthCheck
methodisLiveness
is now defaultfalse
instead oftrue
. -
Added
position
method toorg.apache.camel.StreamCache
. -
The method
configure
from the interfaceorg.apache.camel.main.Listener
was removed -
The
org.apache.camel.support.EventNotifierSupport
abstract class now implementsCamelContextAware
.
EIP Changes
Removed lang
attribute for the <description>
on every EIPs.
The InOnly
and InOut
EIPs has been removed. Instead, use SetExchangePattern
or To
where you can specify exchange pattern to use.
Tracing
The Tracer and Backlog Tracer no longer includes internal tracing events from routes that was created by Rest DSL or route templates or Kamelets. You can turn this on, by setting traceTemplates=true
in the tracer.
UseOriginalMessage / UseOriginalBody
When useOriginalMessage
or useOriginalBody
is enabled in OnException
, OnCompletion
or error handlers, then the original message body is defensively copied and if possible converted to StreamCache
to ensure the body can be re-read when accessed. Previously the original body was not converted to StreamCache
which could lead to the body not able to be read or the stream has been closed.
Camel Health
Health checks are now by default only readiness checks out of the box.
Camel provides the CamelContextCheck
as both readiness and liveness checks, so there is at least one of each out of the box.
JMX
Camel now also include MBeans for doCatch
and doFinally
in the tree of processor MBeans.
The ManagedChoiceMBean
have renamed choiceStatistics
to extendedInformation
. The ManagedFailoverLoadBalancerMBean
have renamed exceptionStatistics
to extendedInformation
.
YAML DSL
The backwards compatible mode Camel 3.14 or older, which allowed to have steps as child to route has been removed.
The old syntax:
- route:
from:
uri: "direct:info"
steps:
- log: "message"
should be changed to:
- route:
from:
uri: "direct:info"
steps:
- log: "message"
Backlog Tracing
The option backlogTracing=true
now automatic enabled the tracer on startup. The previous behavior was surprisingly that the tracer was only made available, and had to be manually enabled afterwards. The old behavior can be archived by setting backlogTracingStandby=true
.
Move the following class from org.apache.camel.api.management.mbean.BacklogTracerEventMessage
in camel-management-api
JAR to org.apache.camel.spi.BacklogTracerEventMessage
in camel-api
JAR.
The org.apache.camel.impl.debugger.DefaultBacklogTracerEventMessage
has been refactored into an interface org.apache.camel.spi.BacklogTracerEventMessage
with some additional details about traced messages. For example Camel now captures a first and last trace that contains the input and outgoing (if InOut
) messages.
XML serialization
The default xml serialization using ModelToXMLDumper
has been improved and now uses a generated xml serializer located in the camel-xml-io
module instead of the JAXB based one from camel-jaxb
.
CircuitBreaker EIP
The following options in camel-resilience4j
was mistakenly not defined as attributes:
Option |
bulkheadEnabled |
bulkheadMaxConcurrentCalls |
bulkheadMaxWaitDuration |
timeoutEnabled |
timeoutExecutorService |
timeoutDuration |
timeoutCancelRunningFuture |
These options were not exposed in YAML DSL, and in XML DSL you need to migrate from:
<circuitBreaker>
<resilience4jConfiguration>
<timeoutEnabled>true</timeoutEnabled>
<timeoutDuration>2000</timeoutDuration>
</resilience4jConfiguration>
...
</circuitBreaker>
To use attributes instead:
<circuitBreaker>
<resilience4jConfiguration timeoutEnabled="true" timeoutDuration="2000"/>
...
</circuitBreaker>
Component changes
Category
The number of enums for org.apache.camel.Category
has been reduced from 83 to 37, which means custom components that are using removed values need to choose one of the remainder values. We have done this to consolidate the number of categories of all components in the Camel community.
camel-azure-cosmosdb
The itemPartitionKey
has been updated. It’s now a String a not a PartitionKey anymore. More details in CAMEL-19222.
camel-bean
When using the method
option to refer to a specific method, and using parameter types and values, such as: "bean:myBean?method=foo(com.foo.MyOrder, true)"
then any class types must now be using .class
syntax, i.e. com.foo.MyOrder
should now be com.foo.MyOrder.class
.
The example from above should now be as follows:
"bean:myBean?method=foo(com.foo.MyOrder.class, true)"
This also applies to Java types such as String, int, etc:
"bean:myBean?method=bar(String.class, int.class)"
camel-caffeine
The keyType
parameter has been removed. The Key for the cache will now be only String
type. More information in CAMEL-18877.
camel-fhir
The underlying hapi-fhir
library has been upgraded from 4.2.0 to 6.2.4. Only the Delete
API method has changed and now returns ca.uhn.fhir.rest.api.MethodOutcome
instead of org.hl7.fhir.instance.model.api.IBaseOperationOutcome
. See https://hapifhir.io/hapi-fhir/blog/ for a more detailed list of underlying changes (only the hapi-fhir client is used in Camel).
camel-http
The component has been upgraded to use Apache HttpComponents v5 which has an impact on how the underlying client is configured. There are 4 different timeouts (connectionRequestTimeout
, connectTimeout
, soTimeout
and responseTimeout
) instead of initially 3 (connectionRequestTimeout
, connectTimeout
and socketTimeout
) and the default value of some of them has changed so please refer to the documentation for more details.
Please note that the socketTimeout
has been removed from the possible configuration parameters of HttpClient
, use responseTimeout
instead.
Finally, the option soTimeout
along with any parameters included into SocketConfig
, need to be prefixed by httpConnection.
, the rest of the parameters including those defined into HttpClientBuilder
and RequestConfig
still need to be prefixed by httpClient.
like before.
camel-http-common
The API in org.apache.camel.http.common.HttpBinding
has changed slightly to be more reusable. The parseBody
method now takes in HttpServletRequest
as input parameter. And all HttpMessage
has been changed to generic Message
types.
camel-kubernetes
The io.fabric8:kubernetes-client
library has been upgraded and some deprecated API usage has been removed. Operations previously prefixed with replace
are now prefixed with update
.
For example replaceConfigMap
is now updateConfigMap
, replacePod
is now updatePod
etc. The corresponding constants in class KubernetesOperations
are also renamed. REPLACE_CONFIGMAP_OPERATION
is now UPDATE_CONFIGMAP_OPERATION
, REPLACE_POD_OPERATION
is now UPDATE_POD_OPERATION
etc.
camel-micrometer
The metrics has been renamed to follow Micrometer naming convention Naming Meters.
Old Name | New Name |
CamelExchangeEventNotifier | camel.exchange.event.notifier |
CamelExchangesFailed | camel.exchanges.failed |
CamelExchangesFailuresHandled | camel.exchanges.failures.handled |
CamelExchangesInflight | camel.exchanges.external.redeliveries |
CamelExchangesSucceeded | camel.exchanges.succeeded |
CamelExchangesTotal | camel.exchanges.total |
CamelMessageHistory | camel.message.history |
CamelRoutePolicy | camel.route.policy |
CamelRoutePolicyLongTask | camel.route.policy.long.task |
CamelRoutesAdded | camel.routes.added |
CamelRoutesRunning | camel.routes.running |
camel-jbang
The command camel dependencies
has been renamed to camel dependency
.
In Camel JBang the -dir
parameter for init
and run
goal has been renamed to require 2 dashes --dir
like all the other options.
camel-openapi-java
The camel-openapi-java
component has been changed to use io.swagger.v3
libraries instead of io.apicurio.datamodels
. As a result, the return type of the public method org.apache.camel.openapi.RestOpenApiReader.read() is now io.swagger.v3.oas.models.OpenAPI
instead of io.apicurio.datamodels.openapi.models.OasDocument
. When an OpenAPI 2.0 (swagger) specification is parsed, it is automatically upgraded to OpenAPI 3.0.x by the swagger parser. This version also supports OpenAPI 3.1.x specifications. The related spring-boot starter components have been modified to use the new return type.
camel-optaplanner
The camel-optaplanner
component has been change to use SolverManager
. If you were using SoverManager
in Camel 3, you don’t need anymore the boolean useSolverManager in the Route. Deprecated ProblemFactChange
has been replaced by ProblemChange
.
The new URI path is:
from("optaplanner:myProblemName")
.to("...")
You can pass the Optaplanner SolverManager in 2 ways:
-
as #parameter
-
as header
When running camel-optaplanner
on Spring Boot or Quarkus, it is preferable to use the Spring Boot or Quarkus way of creating the SolverManager.
It is possible to migrate legacy Camel Optaplanner Routes, by putting the XML config file, as show in the code below. Camel Optaplanner will handle creating the SolverManager for those legacy Routes:
from("optaplanner:myProblemName?configFile=PATH/TO/CONFIG.FILE.xml")
.to("...")
Solver Daemon solutions should be migrated to use SolverManager.
Camel Spring Boot
The camel-spring-boot
dependency no longer includes camel-spring-xml
. To use legacy Spring XML files <beans>
with Camel on Spring Boot, then include the camel-spring-boot-xml-starter
dependency.
Graceful Shutdown
Camel now shutdowns a bit later during Spring Boot shutdown. This allows Spring Boot graceful shutdown to complete first (stopping Spring Boot HTTP server gracefully), and then afterward Camel is doing its own Graceful Shutdown.
Technically camel-spring
has changed getPhase()
from returning Integer.MAX_VALUE
to Integer.MAX_VALUE - 2049
. This gives room for Spring Boot services to shut down first.
camel-micrometer-starter
The uri
tags are now static instead of dynamic (by default), as potential too many tags generated due to URI with dynamic values. This can be enabled again by setting camel.metrics.uriTagDynamic=true
.
camel-platform-http-starter
The platform-http-starter
has been changed from using camel-servlet
to use Spring HTTP server directly. Therefore, all the HTTP endpoints are no longer prefixed with the servlet context-path (default is camel
).
For example:
from("platform-http:myservice")
.to("...")
Then calling myservice would before require to include the context-path, such as http://localhost:8080/camel/myservice
. Now the context-path is not in use, and the endpoint can be called with http://localhost:8080/myservice
.
The platform-http-starter can also be used with Rest DSL. |
If the route or consumer is suspended then http status 503 is now returned instead of 404.