From cc6076ec6b2a0cada71d846444922372798cb7bf Mon Sep 17 00:00:00 2001 From: Chris Bono Date: Wed, 18 Jan 2023 21:43:21 -0600 Subject: [PATCH] Add docs for custom schema mappings See #269 --- .../src/main/asciidoc/pulsar.adoc | 25 ++---------- .../src/main/asciidoc/reactive-pulsar.adoc | 22 ++--------- .../PulsarListener/listener-snippet.adoc | 9 +++++ .../listener-snippet.adoc | 10 +++++ .../schema-info/schema-info-listener.adoc | 29 ++++++++++++++ .../schema-info/schema-info-template.adoc | 38 +++++++++++++++++++ 6 files changed, 94 insertions(+), 39 deletions(-) create mode 100644 spring-pulsar-docs/src/main/asciidoc/schema-info/PulsarListener/listener-snippet.adoc create mode 100644 spring-pulsar-docs/src/main/asciidoc/schema-info/ReactivePulsarListener/listener-snippet.adoc create mode 100644 spring-pulsar-docs/src/main/asciidoc/schema-info/schema-info-listener.adoc create mode 100644 spring-pulsar-docs/src/main/asciidoc/schema-info/schema-info-template.adoc diff --git a/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc b/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc index 97ed1e29..bda00585 100644 --- a/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc +++ b/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc @@ -86,20 +86,8 @@ template.newMessage(msg) ---- ==== -=== Specifying Schema Information -If you use Java primitive types, the framework auto-detects the schema for you, and you need not specify any schema types for publishing the data. -However, if you use any complex types (such as `JSON`, `AVRO`, `PROTOBUF`, and others), you need to set the proper schema type on the `PulsarTemplate` before invoking any send operations, as the following example shows for JSON: - -==== -[source, java] ----- -pulsarTemplate.setSchema(Schema.JSON(Foo.class)); ----- -==== - -IMPORTANT: Complex Schema types that are currently supported are JSON, AVRO, PROTOBUF, and KEY_VALUE w/ INLINE encoding. - -See the <> for Pulsar producer properties. +:template-class: PulsarTemplate +include::schema-info/schema-info-template.adoc[leveloffset=+1] [[pulsar-producer-factory]] === Pulsar Producer Factory @@ -320,13 +308,8 @@ void listen(String message) { TIP: The properties used are direct Pulsar consumer properties, not the `spring.pulsar.consumer` application configuration properties - -=== Specifying Schema Information - -As indicated earlier, for Java primitives, the Spring Pulsar framework can infer the proper Schema to use on the `PulsarListener`. -However, for more complex types (such as JSON or AVRO), you need to specify the schema type on the annotation. - -IMPORTANT: Complex Schema types that are currently supported are JSON, AVRO, PROTOBUF, and KEY_VALUE w/ INLINE encoding. +:listener-class: PulsarListener +include::schema-info/schema-info-listener.adoc[leveloffset=+1] === Accessing the Pulsar Consumer Object Sometimes, you need direct access to the Pulsar Consumer object. diff --git a/spring-pulsar-docs/src/main/asciidoc/reactive-pulsar.adoc b/spring-pulsar-docs/src/main/asciidoc/reactive-pulsar.adoc index 52138868..ec9e3a87 100644 --- a/spring-pulsar-docs/src/main/asciidoc/reactive-pulsar.adoc +++ b/spring-pulsar-docs/src/main/asciidoc/reactive-pulsar.adoc @@ -101,18 +101,8 @@ template.newMessage(msg) TIP: Note that, when using a `MessageRouter`, the only valid setting for `spring.pulsar.reactive.sender.message-routing-mode` is `custom`. -=== Specifying Schema Information -If you use Java primitive types, the framework auto-detects the schema for you, and you need not specify any schema types for publishing the data. -However, if you use any complex types (such as `JSON`, `AVRO`, `PROTOBUF`, and others), you need to set the proper schema type on the `ReactivePulsarTemplate` before invoking any send operations, as the following example shows for JSON: - -==== -[source, java] ----- -template.setSchema(Schema.JSON(Foo.class)); ----- -==== - -IMPORTANT: Complex Schema types that are currently supported are JSON, AVRO, PROTOBUF, and KEY_VALUE w/ INLINE encoding. +:template-class: ReactivePulsarTemplate +include::schema-info/schema-info-template.adoc[leveloffset=+1] [[reactive-sender-factory]] === ReactivePulsarSenderFactory @@ -306,12 +296,8 @@ ReactiveMessageConsumerBuilderCustomizer directConsumerPropsCustomizer() CAUTION: The properties used are direct Pulsar consumer properties, not the `spring.pulsar.reactive.consumer` Spring Boot configuration properties -=== Specifying Schema Information - -As indicated earlier, for Java primitives, the Spring Pulsar framework can infer the proper Schema to use on the `ReactivePulsarListener`. -However, for more complex types (such as JSON or AVRO), you need to specify the schema type on the annotation. - -IMPORTANT: Complex Schema types that are currently supported are JSON, AVRO, PROTOBUF, and KEY_VALUE w/ INLINE encoding. +:listener-class: ReactivePulsarListener +include::schema-info/schema-info-listener.adoc[leveloffset=+1] [[reactive-message-listener-container]] === Message Listener Container Infrastructure diff --git a/spring-pulsar-docs/src/main/asciidoc/schema-info/PulsarListener/listener-snippet.adoc b/spring-pulsar-docs/src/main/asciidoc/schema-info/PulsarListener/listener-snippet.adoc new file mode 100644 index 00000000..183880d3 --- /dev/null +++ b/spring-pulsar-docs/src/main/asciidoc/schema-info/PulsarListener/listener-snippet.adoc @@ -0,0 +1,9 @@ +==== +[source,java,subs="attributes,verbatim"] +---- +@PulsarListener(subscriptionName = "user-sub", topics = "user-topic") +public void listen(User user) { + System.out.println(user); +} +---- +==== diff --git a/spring-pulsar-docs/src/main/asciidoc/schema-info/ReactivePulsarListener/listener-snippet.adoc b/spring-pulsar-docs/src/main/asciidoc/schema-info/ReactivePulsarListener/listener-snippet.adoc new file mode 100644 index 00000000..c8ca46a1 --- /dev/null +++ b/spring-pulsar-docs/src/main/asciidoc/schema-info/ReactivePulsarListener/listener-snippet.adoc @@ -0,0 +1,10 @@ +==== +[source,java,subs="attributes,verbatim"] +---- +@ReactivePulsarListener(topics = "user-topic") +Mono listen(User user) { + System.out.println(user); + return Mono.empty(); +} +---- +==== diff --git a/spring-pulsar-docs/src/main/asciidoc/schema-info/schema-info-listener.adoc b/spring-pulsar-docs/src/main/asciidoc/schema-info/schema-info-listener.adoc new file mode 100644 index 00000000..322763f6 --- /dev/null +++ b/spring-pulsar-docs/src/main/asciidoc/schema-info/schema-info-listener.adoc @@ -0,0 +1,29 @@ +== Specifying Schema Information + +As indicated earlier, for Java primitives, the Spring Pulsar framework can infer the proper Schema to use on the `{listener-class}`. +However, for more complex types (such as JSON or AVRO), you need to specify the schema type on the annotation. + +IMPORTANT: Complex Schema types that are currently supported are JSON, AVRO, PROTOBUF, and KEY_VALUE w/ INLINE encoding. + +=== Custom Schema Resolver +As an alternative to specifying the schema on the `{listener-class}` for complex types, a custom schema resolver can be configured with mappings for the types. +This removes the need to set the schema on the listener as the framework consults the resolver using the incoming message type. + +The following example shows a custom resolver with mappings for the `User` and `Address` complex objects using `AVRO` and `JSON` schemas, respectively: + +==== +[source, java] +---- +@Bean +public SchemaResolver customSchemaResolver() { + Map, Schema> customMappings = new HashMap<>(); + customMappings.put(User.class, Schema.AVRO(User.class)); + customMappings.put(Address.class, Schema.JSON(Address.class)); + return new DefaultSchemaResolver(customMappings); +} +---- +==== + +With this configuration in place, there is no need to set the schema on the listener, for example: + +include::{listener-class}/listener-snippet.adoc[] diff --git a/spring-pulsar-docs/src/main/asciidoc/schema-info/schema-info-template.adoc b/spring-pulsar-docs/src/main/asciidoc/schema-info/schema-info-template.adoc new file mode 100644 index 00000000..f4ce85fb --- /dev/null +++ b/spring-pulsar-docs/src/main/asciidoc/schema-info/schema-info-template.adoc @@ -0,0 +1,38 @@ +== Specifying Schema Information +If you use Java primitive types, the framework auto-detects the schema for you, and you need not specify any schema types for publishing the data. +However, if you use any complex types (such as `JSON`, `AVRO`, `PROTOBUF`, and others), you need to set the proper schema type on the `{template-class}` before invoking any send operations, as the following example shows for JSON: + +==== +[source, java] +---- +template.setSchema(Schema.JSON(Foo.class)); +---- +==== + +IMPORTANT: Complex Schema types that are currently supported are JSON, AVRO, PROTOBUF, and KEY_VALUE w/ INLINE encoding. + +=== Custom Schema Resolver +As an alternative to specifying the schema on the `{template-class}` for complex types, a custom schema resolver can be configured with mappings for the types. +This removes the need to set the schema on the template as the framework consults the resolver using the outgoing message type. + +The following example shows a custom resolver with mappings for the `User` and `Address` complex objects using `AVRO` and `JSON` schemas, respectively: +==== +[source, java] +---- +@Bean +public SchemaResolver customSchemaResolver() { + Map, Schema> customMappings = new HashMap<>(); + customMappings.put(User.class, Schema.AVRO(User.class)); + customMappings.put(Address.class, Schema.JSON(Address.class)); + return new DefaultSchemaResolver(customMappings); +} +---- +==== +With this configuration in place, there is no need to set the schema on the template, for example: +==== +[source, java] +---- +template.send("user-topic", someUserObject); +template.send("address-topic", someAddressObject); +---- +====