docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_1.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 Camel 4.0 to 4.1

=== camel-api

Added method `newInstance(Class<T> type, Class<?> factoryClass, String factoryMethod)`
to `org.apache.camel.spi.Injector`.

Added `isIgnoreLoadingError` and `setIgnoreLoadingError` methods to `org.apache.camel.spi.RoutesLoader`,
and `org.apache.camel.main.RoutesCollector`.

Added `getDuration` method to `org.apache.camel.StartupStep`.

=== XML and YAML DSL

==== Creating beans from script

In route templates (or kamelets), for advanced use cases, you are able to create beans from an inlined script.

The name of the script was defined in `type`, but has been changed to a new `scriptLanguage` attribute.
And `beanType` has been removed as you must use `type` instead.

Before:

[tabs]
====
XML::
+
[source,xml]
----
    <bean name="myBean" type="groovy" beanType="com.foo.MyBean">
        <script>
          <!-- groovy code here to create the bean -->
        </script>
    </bean>
----
YAML::
+
[source,yaml]
----
- beans:
  - name: "myClient"
    beanType: "com.foo.MyBean"
    type: "groovy"
    script: |
      # groovy script here
----
====

After:

[tabs]
====
XML::
+
[source,xml]
----
    <bean name="myBean" type="com.foo.MyBean"
          scriptLanguage="groovy">
        <script>
          <!-- groovy code here to create the bean -->
        </script>
    </bean>
----
YAML::
+
[source,yaml]
----
- beans:
  - name: "myClient"
    type: "com.foo.MyBean"
    scriptLanguage: "groovy"
    script: |
      # groovy script here
----
====

=== camel-management

Dumping routes to JMX no longer includes `customId="true"` in the XML nodes.

=== camel-scheduler

The `scheduler` no longer includes header with the timestamp of when the exchange was fired.
This means the exchange by default has no headers, and `null` body.

The option `includeMetadata` can be set to `true` on the endpoint or component level, to turn on
these additional metadata headers again.

=== camel-timer

The `timer` no longer includes header `firedTime` with the timestamp of when the exchange was fired.
This means the exchange by default has no headers, and `null` body.

The `firedTime` header has been renamed to `CamelTimerFireTime`.

The option `includeMetadata` can be set to `true` on the endpoint or component level, to turn on
these additional metadata headers again.

=== camel-aws2-step-functions

The following Message Headers of `camel-aws2-step-functions` component have been renamed to follow standard camel naming convention.

[cols="1,1"]
|===
|Old Name|New Name

|CamelAwsStateMachineOperation
|CamelAwsStepFunctionsOperation

|CamelAwsStateMachinesMaxResults
|CamelAwsStepFunctionsStateMachinesMaxResults

|CamelAwsStepFunctionsStateMachineActivityName
|CamelAwsStepFunctionsActivityName

|CamelAwsStepFunctionsStateMachineActivityArn
|CamelAwsStepFunctionsActivityArn

|CamelAwsStateMachineActivitiesMaxResults
|CamelAwsStepFunctionsActivitiesMaxResults

|CamelAwsStateMachineExecutionArn
|CamelAwsStepFunctionsExecutionArn

|CamelAwsStateMachineExecutionName
|CamelAwsStepFunctionsExecutionName

|CamelAwsStateMachineExecutionInput
|CamelAwsStepFunctionsExecutionInput

|CamelAwsStateMachineExecutionTraceHeader
|CamelAwsStepFunctionsExecutionTraceHeader

|CamelAwsStateMachineExecutionHistoryMaxResults
|CamelAwsStepFunctionsExecutionHistoryMaxResults

|CamelAwsStateMachineExecutionHistoryIncludeExecutionData
|CamelAwsStepFunctionsExecutionHistoryIncludeExecutionData

|CamelAwsStateMachineExecutionHistoryReverseOrder
|CamelAwsStepFunctionsExecutionHistoryReverseOrder

|CamelAwsStateMachineExecutionMaxResults
|CamelAwsStepFunctionsExecutionMaxResults
|===

This is applicable only if literal constant headers are used such as `CamelAwsStateMachinesMaxResults`. If the headers are used from StepFunctions2Constants Interface like StepFunctions2Constants.STATE_MACHINES_MAX_RESULTS , then there is no change;

For Example before

----
from("direct:listActivities")
  .setHeader("CamelAwsStepFunctionsActivitiesMaxResults",5)
   .to("aws2-step-functions://test?awsSfnClient=#awsSfnClient&operation=listActivities")
----

Should be changed to

----
from("direct:listActivities")
  .setHeader("CamelAwsStepFunctionsActivitiesMaxResults",5)
    .to("aws2-step-functions://test?awsSfnClient=#awsSfnClient&operation=listActivities")
----

=== camel-aws2-sns

The `queueUrl` parameter has been replaced by the `queueArn` parameter

For Example before

----
from("direct:start")
  .to("aws2-sns://mytopic?subject=mySubject&autoCreateTopic=true&subscribeSNStoSQS=true&queueUrl=https://xxxx")
----

Should be changed to

----
from("direct:start")
  .to("aws2-sns://mytopic?subject=mySubject&autoCreateTopic=true&subscribeSNStoSQS=true&queueArn=arn:aws:sqs:xxxxx")
----

=== camel-pdf

The Camel-PDF component has been updated to Apache PDFBox 3.0.0, and the font parameter is now defined through the following enum values: COURIER,COURIER_BOLD,COURIER_OBLIQUE,COURIER_BOLD_OBLIQUE, HELVETICA,HELVETICA_BOLD,HELVETICA_OBLIQUE,HELVETICA_BOLD_OBLIQUE,TIMES_ROMAN,TIMES_BOLD,TIMES_ITALIC,TIMES_BOLD_ITALIC,SYMBOL and ZAPF_DINGBATS

=== camel-jbang

The `pipe` command has been renamed to `script`.

The `--secrets-refresh` and `--secret-refresh-providers` have been removed, since they were logically incorrect in the export command context. More information at CAMEL-19927 issue.

The generated XML route, created using the command `camel init`, now uses `<camel>` as the root tag instead of `<routes>`.

=== camel-jetty / camel-servlet / camel-atmosphere-websocket / camel-http-common

By default, stack traces will not be included in HTTP responses,
exceptions are muted.
Stack traces can be included in HTTP responses by disabling `muteException`.
For example:

----
from("jetty:http://localhost:{{port}}/myapp/myservice?muteException=false")
----

When exceptions are muted stack traces may be logged by enabling `logException`.
For example

----
from("jetty:http://localhost:{{port}}/myapp/myservice?logException=true")
----

=== YAML DSL

The kebab-case style schema file,  `camel-yaml-dsl.json` has been removed from the distribution in favor of the camelCase style schema file, `camelYamlDsl.json`. While the Camel runtime stays supporting kebab-case style also for the moment, it is recommended to migrate to camelCase style. Any tooling should encourage users to use camelCase style.

=== camel-tracing

The `Tag` Enum containing constants for tagging spans has been deprecated.
Instead,
use constants from the `TagConstants` Class that align to Open Telemetry v1.21.0 semantic conventions.

For example, instead of

----
span.setTag(Tag.URL_SCHEME, scheme);
----

use

----
span.setTag(TagConstants.URL_SCHEME, scheme);
----

=== camel-kafka

The default value for `sessionTimeoutMs` has been updated to  `45000` ms, while the default value for `consumerRequestTimeoutMs` has been updated to `30000`. More information in CAMEL-19921 issue.

=== camel-core, rest

A new rest configuration option, `enableNoContentResponse`,
allows HTTP 204 to be returned with an empty body if a Message contains an empty JSON object or empty XML root object when set to `true`.