davsclaus commented on code in PR #2018:
URL:
https://github.com/apache/camel-spring-boot/pull/2018#discussion_r4184426557
##########
docs/spring-boot/modules/ROOT/pages/jackson.adoc:
##########
@@ -0,0 +1,253 @@
+= Jackson 2 and Jackson 3
+
+Since version 4.19, Camel Spring Boot is based on Spring Boot 4, which uses
Jackson 3 (`tools.jackson`) by default.
+Camel supports both Jackson lines:
+
+[options="header"]
+|===
+| Jackson 2 (`com.fasterxml.jackson`) | Jackson 3 (`tools.jackson`)
+| xref:starters/jackson.adoc[`camel-jackson-starter`] |
xref:starters/jackson3.adoc[`camel-jackson3-starter`]
+| xref:starters/jacksonxml.adoc[`camel-jacksonxml-starter`] |
xref:starters/jackson3xml.adoc[`camel-jackson3xml-starter`]
+| xref:starters/jackson-avro.adoc[`camel-jackson-avro-starter`] |
xref:starters/jackson3-avro.adoc[`camel-jackson3-avro-starter`]
+| xref:starters/jackson-protobuf.adoc[`camel-jackson-protobuf-starter`] |
xref:starters/jackson3-protobuf.adoc[`camel-jackson3-protobuf-starter`]
+|===
+
+Both lines register the same data format names (`jackson`, `jacksonXml`,
`avroJackson`, `protobufJackson`), the same
+data type transformers (`application-json`, ...) and the same configuration
prefix (`camel.dataformat.jackson.*`), so
+routes and properties do not need to change when switching. As a consequence,
*only one line can be used in an
+application*.
+
+Many Camel components (for example Kafka, Salesforce, OpenAPI, Micrometer) use
Jackson 2 internally, so the Jackson 2
+libraries are often on the classpath next to Spring Boot's Jackson 3. This is
expected and supported: the two lines
+use different Java packages. Only the Camel Jackson modules listed above must
not be mixed.
+
+== Rules
+
+* Use either `camel-jackson-starter` or `camel-jackson3-starter`, never both.
With both on the classpath the
+ application fails to start with a `BeanDefinitionOverrideException` for
`configureJacksonDataFormatFactory`.
+ The same applies to the XML, Avro and Protobuf variants.
+* Some starters bring `camel-jackson` (Jackson 2) transitively:
`camel-mongodb-starter`,
+ `camel-mongodb-gridfs-starter`, `camel-jq-starter`, `camel-neo4j-starter`,
`camel-aws-bedrock-starter`,
+ `camel-google-vertexai-starter` and `camel-dhis2-starter`. If you combine
them with `camel-jackson3-starter`, the
+ order of the dependencies decides, without any warning, which data format
`marshal().json()`, REST DSL binding and
+ the JSON transformers use. When the Jackson 2 data format wins, the
`camel.dataformat.jackson.*` properties are not
+ applied at all, because they only apply to the Jackson 3 data format.
++
+Check with:
++
+[source,bash]
+----
+mvn dependency:tree
-Dincludes=org.apache.camel:camel-jackson,org.apache.camel:camel-jackson3
+----
++
+In that case, either declare `camel-jackson3-starter` before those starters,
or reference the data format explicitly:
+`marshal("jackson")` with a Jackson 3 `JacksonDataFormat` bean, or an instance
passed to `marshal()`. Configure that
+bean in Java: while `camel-jackson` comes first on the classpath, setting any
`camel.dataformat.jackson.*` property
+makes the application fail to start with a `PropertyBindingException`. Do not
exclude `camel-jackson` from those starters: they need it.
Review Comment:
Small clarification: L33-34 say that when the Jackson 2 data format wins,
the `camel.dataformat.jackson.*` properties "are not applied at all" (which
matches the starter's customizer, since it only targets the Jackson 3
`JacksonDataFormat` via `instanceof`). Here it says setting any of them makes
startup fail with a `PropertyBindingException`. Both may be true if the
exception comes from a different binding path, but as written a reader may see
them as contradictory. Could you say briefly where the exception comes from, or
adjust L34 to something like "the starter does not apply them to the Jackson 2
data format"?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
