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 from 4.10.0 to 4.10.1

camel-ftp

The file name header Exchange.FILE_NAME now includes the relative path such as subdir/hello.txt when using recursive=true, to be similar to how camel-file component behaves.

Upgrading Camel 4.9 to 4.10

XML DSL changes

In <intercept> and <interceptSendToEndpoint> then <when> has been renamed to <onWhen>.

For example:

<intercept>
  <when>...</when>
  ...
</intercept>

Should now be:

<intercept>
  <onWhen>...</onWhen>
  ...
</intercept>

In <circuitBreaker the <onFallback> section must be configured last.

For example:

  <circuitBreaker>
    <resilience4jConfiguration timeoutEnabled="true" timeoutDuration="2000"/>
    <onFallback>
      <transform>
        <constant>Fallback message</constant>
      </transform>
    </onFallback>
    <to uri="direct:foo"/>
    ...
  </circuitBreaker>

Should now be:

  <circuitBreaker>
    <resilience4jConfiguration timeoutEnabled="true" timeoutDuration="2000"/>
    <to uri="direct:foo"/>
    ...
    <onFallback>
      <transform>
        <constant>Fallback message</constant>
      </transform>
    </onFallback>
  </circuitBreaker>

And inheritErrorHandler has been moved from <loadBalance> to <failoverLoadBalancer which is the only load balancer support this option.

For example:

  <loadBalance inheritErrorHandler="true">
    <failoverLoadBalancer maximumFailoverAttempts="3" roundRobin="true"/>
    ...
  </loadBalance>

Should now be:

  <loadBalance>
    <failoverLoadBalancer maximumFailoverAttempts="3" roundRobin="true" inheritErrorHandler="true"/>
    ...
  </loadBalance>

camel-kamelet

The error handling when using kamelets has been refactored to let Kamelets re-use the same error handling that are from the route where the kamelets are being used. Previously Kamelets did not have any error handling.

Suppose you have kamelets that would cause an exception during processing, such as the source below. Now because the route has been configured with a dead letter channel as the error handler, then the exception from the kamelet will be handled by the route error handler. Which means you will se a WARN being logged.

Previously the exception would not be handled by the route error handler, and the kamelet source would always fail internally and cause a WARN being logged. Meaning that you did not have any power to handle these errors.

Now the kamelets are first class and gives users the full power to handle errors as they see fit.

- route:
    errorHandler:
      deadLetterChannel:
        deadLetterUri: log:dead?level=WARN
    id: myRoute
    from:
      uri: "kamelet:my-error-source/source"
      steps:
        - log: "${body}"

This change has most an effect on source Kamelets. For sink or action Kamelets, then any error would be propagated back to the route, that could still handle the error. However, if the error handler is configured to perform retries, then the retry would be starting all over again calling the sink Kamelet. This change will let the error handler perform retries at the original of the error (also inside the Kamelet), the same as regular Camel routes.

So suppose you have the following route:

- route:
    errorHandler:
      deadLetterChannel:
        deadLetterUri: log:dead?level=WARN
        redeliveryPolicy:
          maximumRedeliveries: 5
          redeliveryDelay: "5000"
    id: myRoute
    from:
      uri: "direct:start"
      steps:
        - to:
            uri: "kamelet:my-error-sink/sink"
        - log: "${body}"

Then notice the error handler has been configured to do redeliveries up till 5 times with 5 sec delay between. Suppose the sink kamelet is throwing an exception, then Camel will now perform the redelivery attempt at the point of origin, which means inside the Kamelet. Previously the redelivery will only happen at the route level, calling the kamelet all over again.

The option noErrorHandler has changed default from true to false. You should only use this option if you want to turn on error handling inside Kamelets all together. However, this should only be used in advanced/rare use-cases. This option may in the future be deprecated and removed.

camel-azure-files

The class org.apache.camel.component.file.azure.FilesHeaders has been renamed to org.apache.camel.component.file.azure.FilesConstants.

camel-aws2-s3

The header CamelAwsS3BucketName for setting a bucket to write to, on the producer side, cannot be used anymore: the header CamelAwsS3OverrideBucketName must be used instead. This was done to avoid situation in which you’re moving a file from a bucket to a different one, and the header coming from the S3 consumer is used as bucket name for S3 Producer. You can find more information on CAMEL-21680.

camel-file

The camel-file consumer has been optimized when filtering file names using name matching only, to avoid creating an GenericFile object that represent the file. This is unnessasary if the file is to be excluded due the filtering.

This optimization has changed APIs in the camel-file component to let methods that accept GenericFile as parameter, has been changed to use a Supplier<GenericFile> to lazy create the wrapper.

Camel users who have created 3rd party component extending camel-file may need to migrate your components.

camel-google-storage

The header CamelGoogleCloudStorageBucketName for setting a bucket to write to, on the producer side, cannot be used anymore: the header CamelGoogleCloudStorageOverrideBucketName must be used instead. This was done to avoid situation in which you’re moving a file from a bucket to a different one, and the header coming from the Google Storage consumer is used as bucket name for Google Storage Producer. You can find more information on CAMEL-21682.

camel-jgroups

The cluster lock has been removed as it has been removed in JGroups 5.4 onwards, and it was not recommended to be used in older JGroups releases. You can use another Camel component such as camel-infinispan that has cluster locking.

The camel-jgroups-cluster-service-starter in Camel Spring Boot has been removed.

camel-jbang

The camel-jbang commands for camel-k has been removed.

The camel dependency update has removed the option --source to specify the source file, but to refer to the source file directly such as:

camel dependency update --source=MyRoute.java to be camel dependency update MyRoute.java.

camel-micrometer

We have fixed a flawed behavior when using dynamic endpoints which made the generation of endpoint events to grow in an uncontrolled way. From now on the component will generate events for the endpoint base URI as a default behavior. If you still want to collect events for the extended URI (including the parameters), then, you can use the camel.metrics.baseEndpointURIExchangeEventNotifier=false configuration. Mind that this is strongly discouraged as it can make your number of events growing out of control.

camel-mina

If using object codec, then you should configure the objectCodecPattern configuration to specify which java classes (FQN) to allow for Object serialization. You can use * to accept all patterns.

camel-minio

The header CamelMinioBucketName for setting a bucket to write to, on the producer side, cannot be used anymore: the header CamelMinioOverrideBucketName must be used instead. This was done to avoid situation in which you’re moving a file from a bucket to a different one, and the header coming from the Minio consumer is used as bucket name for Minio Producer. You can find more information on CAMEL-21678.

camel-google-pubsub-lite

The component camel-google-pubsub-lite has been deprecated following the deprecation of the corresponding service by Google Cloud Platform.

Google recommends migrating your Pub/Sub Lite service to either Google Cloud Managed Service for Apache Kafka or Google Cloud Pub/Sub. Depending on your choice, you should use camel-kafka or camel-google-pubsub component, respectively.

camel-tracing

We have deprecated the setting of MDC trace_id and span_id in favour of implementation specific feature. You need to check the specific tracing/telemetry component configuration to learn how to switch from the deprecated configuration to the new one. Most of the time you will need to remove the camel.main.use-mdc-logging Camel property (or set it to false) and add dependencies and configuration settings to enable the specific component instrumentation.

camel-langchain4j-chat

The function calling feature was removed. Please use the camel-langchain4j-tools component for function calling.

camel-smb

The camel-smb component has been updated to extend GenericFile classes and now supports more consumer and producer options. The Consumer includes options for filtering, pre and post processing, duplicate handling, directory traversal, polling, and readlocks. The Producer includes options for writing to temporary files, writing content, and handling existing files.

camel-solr

The camel-solr component has been refactored. The solrs and solrCloud schemes have been deprecated in the uri format (but can still be enabled via the enableSSL and solrClient configuration options). The solr operations have been simplified and some solr operations will be no longer be available in the next release. For those operations, a warning message will tell you how to get the same results with the new operations. The Solr component exchange headers have been renamed and extended. As a consequence, the user should review the use of the Solr exchange headers and rename them when applicable.

All the solr headers has been renamed to use CamelSolr as prefix, such as operation → CamelSolrOperation.

camel-spring-boot

The camel-k-starter has been removed.

Back to top