docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_8.adoc

= 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.

[NOTE]
====
https://github.com/apache/camel-upgrade-recipes/[The Camel Upgrade Recipes project] provides automated assistance for some common migration tasks.
Note that manual migration is still required.
See the xref:camel-upgrade-recipes-tool.adoc[documentation] page for details.
====

== Upgrading from 4.8.4 to 4.8.7

=== camel-core

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.

== Upgrading from 4.8.2 to 4.8.3

=== 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.

== Upgrading from 4.8.1 to 4.8.2

=== camel-management

==== Using Route Templates

Camel will now ensure the created routes via route templates
always use unique _nodePrefixId_ to ensure there are no duplicate id clashes, when the template
is used for creating multiple routes.

=== camel-debezium

To avoid split package that can be a problem in environments like OSGI, each camel-debezium module has its own
sub package corresponding to the database type. So for example, all the classes of the module `camel-debezium-postgres`
have been moved to a dedicated package which is `org.apache.camel.component.debezium.postgres` instead of having
everything under the root package `org.apache.camel.component.debezium`.

== Upgrading from 4.8.0 to 4.8.1

The `camel-opentelemetry` component has had significant bug fixes to handle span activation/deactivations
better when Camel route messages synchronously and asynchronously. This component should also work better
on Spring Boot.

In order to fix the problems reported we had to align the Opentelemetry dependencies to a version which is different from the one used in Spring Boot 3.3.x BOM. 
If you're using such BOM for your **Camel Spring Boot runtime** application, you will need to make sure to force the usage of the Opentelemetry dependencies below:

[source, xml]
----
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk</artifactId>
    <version>1.43.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
    <version>1.43.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-context</artifactId>
    <version>1.43.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-logs</artifactId>
    <version>1.43.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-metrics</artifactId>
    <version>1.43.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk-common</artifactId>
    <version>1.43.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk-metrics</artifactId>
    <version>1.43.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk-logs</artifactId>
    <version>1.43.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk-trace</artifactId>
    <version>1.43.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api-incubator</artifactId>
    <version>1.43.0-alpha</version>
</dependency>
----

== Upgrading Camel 4.7 to 4.8

=== camel-api

Added `void bind(String id, Class<?> type, Object bean, String initMethod, String destroyMethod)` method to `org.apache.camel.spi.Registry`
to support init and destroy method on beans.

=== camel-core

The `UseOriginalAggregationStrategy` class will now propagate the caught exception stored in the exchange property `Exchange.EXCEPTION_CAUGHT`
as well. For example, when using the Splitter EIP with this, then any caught exception during splitting would be stored
as well, which allows access to this information afterward, for example, in an `onCompletion` where the caught exception
can be used to know some error happened during splitting.

Internally, Camel will now use Java's own `InputStream.transferTo` for copying data between streams whenever such copies don't
require customized buffer sizes or data flushing policies. Additionally, the size of the data buffer used by Camel when
performing these copies has increased from 4096 bytes to 16384 bytes (the default buffer size used by Java 21).

The tracer (`BacklogTracer`) has changed the `backlogSize` default value from `1000` to `100`, and `maxBodySize` from `128kb` to `32kb`.
This reduces the amount of data captured and stored and helps reduce the tracing overhead.

The `org.apache.camel.support.DefaultExchangeHolder` will now include both exchange variables and properties,
if the parameter `includeProperties` is set to true.

=== camel-jbang

The `camel trace` command has changed to show tracing status (by default). To dump traced messages use `camel trace --action=dump`.

*Breaking changes only in 4.8.0* The parameter `--repos` has been renamed `--repository` for `run` and `export` commands. It requires to be updated when using from command-line and in `application.properties`. In 4.8.1, the `--repos` has been set back and  `--repository` removed.

=== Deprecated Components

The following components that were marked as deprecated:

* camel-univocity-parsers

=== camel-as2

The header prefixes have been corrected from `CamelAS2.` -> `CamelAs2.` to be consistent with naming convention
used by other API-based components. The documentation uses the correct naming prefix as `CamelAs2.`.

=== camel-kafka

The `KafkaIdempotentRepository` will now continue to sync cache updates after Camel has been started.
You can configure `startupOnly=true` to only sync the cache once on startup,
(however, then the cache is not synced with other Camel nodes in a cluster).

=== camel-langchain4j-chat

The chat-with-tools feature was deprecated. Use the new `camel-langchain4j-tool` component.

=== camel-tests

Continuing the multi-release tests cleanups, on this one, restricted methods from the `CamelTestSupport` class
have been marked as final and cannot be extended.

=== Preferred JAX-B implementation: `org.glassfish.jaxb:jaxb-runtime`

We stopped relying on `com.sun.xml.bind:jaxb-impl` in favor of `org.glassfish.jaxb:jaxb-runtime`.
This change should have no impact on existing code, because recent versions of the two artifacts bring the same classes.
The main motivation for this change is to allow projects that still require classes from `javax.xml.bind` package
to be able to depend on pre-3.x versions of `com.sun.xml.bind:jaxb-impl` together with the recent version of
`org.glassfish.jaxb:jaxb-runtime` brought by Camel.