From 760acd181dbea596a3f6ac0b4aeaff59b2829641 Mon Sep 17 00:00:00 2001 From: onobc Date: Thu, 13 Nov 2025 19:31:19 -0600 Subject: [PATCH] Add Jackson2/3 to custom object mapper sections in docs. See #1151 Signed-off-by: onobc --- .../pages/attributes/attributes-variables.adoc | 4 ++-- .../pages/reference/custom-object-mapper.adoc | 18 +++++++++++++++--- .../ROOT/pages/reference/pulsar-header.adoc | 6 +++++- 3 files changed, 22 insertions(+), 6 deletions(-) diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/attributes/attributes-variables.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/attributes/attributes-variables.adoc index 1c0eaa1e6..953b8b1dc 100644 --- a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/attributes/attributes-variables.adoc +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/attributes/attributes-variables.adoc @@ -9,8 +9,8 @@ :github: https://github.com/spring-projects/spring-pulsar :javadocs: https://docs.spring.io/spring-pulsar/docs/{spring-pulsar-version}/api :spring-framework-docs: https://spring.io/projects/spring-framework#learn -:spring-boot-docs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/reference/htmlsingle -:spring-boot-pulsar-config-props: {spring-boot-docs}/#application-properties.integration +:spring-boot-docs: https://docs.spring.io/spring-boot/{spring-boot-version} +:spring-boot-pulsar-config-props: {spring-boot-docs}/appendix/application-properties/index.html#appendix.application-properties.integration :spring-cloud-stream-docs: https://docs.spring.io/spring-cloud-stream/docs/{spring-cloud-stream-version}/reference/html/ :spring-cloud-function: https://spring.io/projects/spring-cloud-function diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/custom-object-mapper.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/custom-object-mapper.adoc index 9484a73a8..0afb097f0 100644 --- a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/custom-object-mapper.adoc +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/custom-object-mapper.adoc @@ -1,9 +1,9 @@ [[custom-object-mapper]] = Custom Object Mapper -include::../attributes/attributes.adoc[] +include::../attributes/attributes-variables.adoc[] -Pulsar uses an internal Jackson `ObjectMapper` when de/serializing JSON messages. -If you instead want to provide your own object mapper instance, you can register a `SchemaResolverCustomizer` and set your mapper on the `DefaultSchemaResolver` as follows: +Pulsar uses an internal shaded Jackson `ObjectMapper` when de/serializing JSON messages. +If you instead want to provide your own Jackson 2 object mapper instance, you can register a `SchemaResolverCustomizer` and set your mapper on the `DefaultSchemaResolver` as follows: [source,java,indent=0,subs="verbatim"] ---- @@ -16,6 +16,8 @@ SchemaResolverCustomizer schemaResolverCustomizer() { } ---- +IMPORTANT: The object mapper in the example above should be an instance of `com.fasterxml.jackson.databind.ObjectMapper`, **not** the shaded `org.apache.pulsar.shade.com.fasterxml.jackson.databind.ObjectMapper`. + This results in your object mapper being used to de/serialize all JSON messages that go through the schema resolution process (i.e. in cases where you do not pass a schema in directly when producing/consuming messages). Under the hood, the resolver creates a special JSON schema which leverages the custom mapper and is used as the schema for all resolved JSON messages. @@ -46,3 +48,13 @@ myObjectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL); ==== NOTE: A later version of the framework may instead provide a customizer that operates on the default mapper rather than requiring a separate instance. + +[[jackson2vs3]] +== Jackson 2 / Jackson 3 +In Spring Boot 4 the default version of {spring-boot-docs}/reference/features/json.html#features.json.jackson[Jackson is 3] and is auto-configured via the spring-boot-starter-json module. +However, Spring for Apache Pulsar expects a {spring-boot-docs}/reference/features/json.html#features.json.jackson2[Jackson 2] custom mapper. + +If you are using Jackson 3 in your Spring Boot 4 application and want to use a custom mapper you will need to add Jackson 2 to the classpath. +Don't worry, Spring Boot 4 allows Jackson 2 and 3 to co-exist in an application. + +NOTE: A later version of the framework may support using a Jackson 2 or Jackson 3 custom mapper. diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/pulsar-header.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/pulsar-header.adoc index c345caa6d..87a71e6c6 100644 --- a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/pulsar-header.adoc +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/pulsar-header.adoc @@ -44,7 +44,7 @@ During inbound mapping, they are mapped as `String`. By default, only `org.springframework.util.MimeType` and `org.springframework.http.MediaType` are mapped this way. ===== Custom ObjectMapper -The JSON mapper uses a reasonable configured Jasckson `ObjectMapper` to handle serialization of header values. +The JSON mapper uses a reasonable configured Jackson 2 `ObjectMapper` to handle serialization of header values. However, to provide a custom object mapper one must simply provide an `ObjectMapper` bean with the name `pulsarHeaderObjectMapper`. For example: [source, java] @@ -61,6 +61,10 @@ static class PulsarHeadersCustomObjectMapperTestConfig { } ---- +IMPORTANT: The object mapper in the example above should be an instance of `com.fasterxml.jackson.databind.ObjectMapper`, **not** the shaded `org.apache.pulsar.shade.com.fasterxml.jackson.databind.ObjectMapper`. + +IMPORTANT: The xref:reference/custom-object-mapper.adoc#jackson2vs3[same limitations] regarding Jackson 2 vs. Jackson 3 apply here } + === Inbound/Outbound Patterns On the inbound side, by default, all Pulsar headers (message metadata plus user properties) are mapped to `MessageHeaders`. On the outbound side, by default, all `MessageHeaders` are mapped, except `id`, `timestamp`, and the headers that represent the Pulsar message metadata (i.e. the headers that are prefixed with `pulsar_message_`).