Apache Camel 3.x Upgrade Guide

This document is for helping you upgrade your Apache Camel application from Camel 3.x to 3.y. For example if you are upgrading Camel 3.0 to 3.2, then you should follow the guides from both 3.0 to 3.1 and 3.1 to 3.2.

Upgrading Camel 3.8 to 3.9

API changes

The Consumer API in camel-api has been enhanced to help support Camel reducing the footprint during routing. One aspect is that we allow to recycle Exchange instances created by the consumers. This avoids creating new Exchange instances in the memory for each incoming message consumers process. By recycling Exchange`s we reduce the overhead on the JVM garbage collector. However this requires Camel to know whether or not the `Exchange should be recycle or not, and some API changes took place.

The Consumer API has two new methods which a consumer must use to create an Exchange with createExchange. By default the exchange is auto released when its complete in use, but some consumers needs custom control, and can turn off auto release, which then requires the consumer to manually release the exchange by calling releaseExchange when the consumer is done with the exchange.

The default implementations in DefaultConsumer has adapted this API and 3rd party components can continue as is, by using the older APIs. However for these 3rd party components to support recycling exchanges, then they must be updated to use this new API.

A new org.apache.camel.spi.ResourceLoader has been introduced as part of CAMEL-16285 which provide a way to support additional schemas to resolve resources. As a conseguence:

  • org.apache.camel.support.ResourceHelper has been updated to use such mechanism instead fo the old one.

  • it is not more possible to provide support for additional schemas using the URL protocol handler mechanism but instead, custom schemas can be added by implementing org.apache.camel.spi.ResourceResolver and either bind an instance to the Camel Registry (using resource-loader- as a prefix) or using the Service Factory mechanism (under the path META-INF/services/org/apache/camel/resource-resolver/)

    As example, assuming you want to provide a support for the schema foo, then you either have to binbd your instance to the Camel Registry with resource-loader-foo as a key, or create a factory finder file with path META-INF/services/org/apache/camel/resource-resolver/foo

  • the method for retrieving a resource URL provided by the org.apache.camel.support.ResourceHelper class, i.e. resolveMandatoryResourceAsUrl ad ` resolveResourceAsUr` have been amended to accept a CamelContext instance instead of a ClassResolver.


Modularized camel-spring

The camel-spring component has been modularized into:

  • camel-spring - Core module for Camel Spring support

  • camel-spring-xml - XML DSL when using Spring XML (eg <beans>)

And also for Camel on Spring Boot:

  • camel-spring-boot-starter - Camel with Spring Boot

  • camel-spring-boot-xml-starter - XML DSL when using Spring XML (eg <beans>) with Spring Boot

The motivation is to move out the XML DSL from camel-spring which reduces the number of dependencies and makes the module lighter.

Users that use the Spring XML DSL (eg the top XML tag is Spring <beans>) should migrate from using camel-spring to camel-spring-xml as dependency.

Users that do not use Spring XML should not be affected.

In Spring XML <proxy> and <remote>` have been removed. They were only available in Spring XML and not in the other XML DSLs (Blueprint and CDI).

camel-spring-boot-starter vs camel-spring-boot-engine-starter

Based on the modularization of camel-spring we have made two starters available when using Camel on Spring Boot

  • camel-spring-boot-starter - The regular starter that includes all the core components (similar to camel-core)

  • camel-spring-boot-engine-starter - A minimal starter with just Camel core engine (similar to camel-core-engine)

We also made all the component -starter JARs not depend on any of the above starters, which means you must pick the one to use above, and then add which -starter JARs you want to use in your Camel spring boot applications.

Camel-AWS components removed

  • Camel-AWS-SDB has been removed. There will be no substitution for this, because there isn’t a SDK v2 client for this and furthermore the service is not listed in the AWS console anymore.

  • Camel-AWS-Translate has been removed. Please switch to Camel-AWS2-Translate.

  • Camel-AWS-SQS has been removed. Please switch to Camel-AWS2-SQS.

  • Camel-AWS-SNS has been removed. Please switch to Camel-AWS2-SNS.

  • Camel-AWS-MSK has been removed. Please switch to Camel-AWS2-MSK.

  • Camel-AWS-MQ has been removed. Please switch to Camel-AWS2-MQ.

  • Camel-AWS-KMS has been removed. Please switch to Camel-AWS2-KMS.

  • Camel-AWS-Kinesis has been removed. Please switch to Camel-AWS2-Kinesis.

  • Camel-AWS-Kinesis Firehose has been removed. Please switch to Camel-AWS2-Kinesis-firehose.

  • Camel-AWS-IAM has been removed. Please switch to Camel-AWS2-IAM.

  • Camel-AWS-EKS has been removed. Please switch to Camel-AWS2-EKS.

  • Camel-AWS-ECS has been removed. Please switch to Camel-AWS2-ECS.

  • Camel-AWS-EC2 has been removed. Please switch to Camel-AWS2-EC2.

  • Camel-AWS-DDB has been removed. Please switch to Camel-AWS2-DDB.

  • Camel-AWS-DDB Streams has been removed. Please switch to Camel-AWS2-DDB Streams.

  • Camel-AWS-CW has been removed. Please switch to Camel-AWS2-CW.

  • Camel-AWS-S3 has been removed. Please switch to Camel-AWS2-S3.

  • Camel-AWS-SWF has been removed. There won’t be a replacement for it.

Camel-Azure component

  • Camel-Azure has been removed. Please switch to Camel-Azure-Storage-Blob and Camel-Azure-Storage-Queue.

camel-freemarker component

The freemarker component now has turned off localized lookup for templates. This can be turned back on by setting localizedLookup=true on the component.