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.

Java versions

Camel 4 supports Java 17. Support for Java 11 is dropped.

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

Logging

Camel 4 has upgraded logging facade API slf4j-api from 1.7 to 2.0.

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

  • Removed getEndpointMap() method from CamelContext.

  • Removed @FallbackConverter as you should use @Converter(fallback = true) instead.

  • Removed uri attribute on @EndpointInject, @Produce, and @Consume as you should use value (default) instead. For example @Produce(uri = "kafka:cheese") should be changed to @Produce("kafka:cheese")

  • Removed label on @UriEndpoint as you should use category instead.

  • Removed all asyncCallback methods on ProducerTemplate. Use asyncSend or asyncRequest instead.

  • Removed org.apache.camel.spi.OnCamelContextStart. Use org.apache.camel.spi.OnCamelContextStarting instead.

  • Removed org.apache.camel.spi.OnCamelContextStop. Use org.apache.camel.spi.OnCamelContextStopping instead.

  • Decoupled the org.apache.camel.ExtendedCamelContext from the org.apache.camel.CamelContext.

  • Replaced adapt() from org.apache.camel.CamelContext with getCamelContextExtension

  • Decoupled the org.apache.camel.ExtendedExchange from the org.apache.camel.Exchange.

  • Replaced adapt() from org.apache.camel.ExtendedExchange with getExchangeExtension

  • 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 and DiscardOldest from org.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 to camel-core-engine for internal use only. End users should use org.apache.camel.spi.BeanInspection instead.

  • Removed archetypeCatalogAsXml method from org.apache.camel.catalog.CamelCatalog.

  • The org.apache.camel.health.HealthCheck method isLiveness is now default false instead of true.

  • Added position method to org.apache.camel.StreamCache.

  • The method configure from the interface org.apache.camel.main.Listener was removed

  • The org.apache.camel.support.EventNotifierSupport abstract class now implements CamelContextAware.

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-platform-http-vertx

If the route or consumer is suspended then http status 503 is now returned instead of 404.

camel-slack

The default delay (on slack consumer) is changed from 0.5s to 10s to avoid being rate limited to often by Slack.

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.

Back to top