diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/nav.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/nav.adoc index cfd1c3ff..ea2882ed 100644 --- a/spring-pulsar-docs/src/main/antora/modules/ROOT/nav.adoc +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/nav.adoc @@ -1,9 +1,10 @@ * xref:index.adoc[Overview] -* xref:intro.adoc[Introduction] -** xref:intro/project-state.adoc[Project Status] -** xref:intro/system-requirements.adoc[System Requirements] -** xref:intro/building.adoc[Building the Project] -** xref:intro/getting-help.adoc[Getting Help] +* xref:whats-new.adoc[] +* xref:intro.adoc[] +** xref:intro/project-state.adoc[] +** xref:intro/system-requirements.adoc[] +** xref:intro/building.adoc[] +** xref:intro/getting-help.adoc[] * xref:reference/reference.adoc[] ** xref:reference/pulsar.adoc[] *** xref:reference/tombstones.adoc[] diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/intro/building.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/intro/building.adoc index 848ba155..dcefce7e 100644 --- a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/intro/building.adoc +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/intro/building.adoc @@ -1,5 +1,5 @@ [[building-project]] -== Building the Project += Building the Project include::../attributes/attributes-variables.adoc[] diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/pulsar.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/pulsar.adoc index 1a0dffe7..d4b8e975 100644 --- a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/pulsar.adoc +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/pulsar.adoc @@ -296,6 +296,7 @@ void listen(String message) { TIP: The properties used are direct Pulsar consumer properties, not the `spring.pulsar.consumer` application configuration properties +[[listener-auto-consume]] ==== Generic records with AUTO_CONSUME If there is no chance to know the type of schema of a Pulsar topic in advance, you can use the `AUTO_CONSUME` schema type to consume generic records. In this case, the topic deserializes messages into `GenericRecord` objects using the schema info associated with the topic. diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/custom-schema-mapping-annotation.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/custom-schema-mapping-annotation.adoc new file mode 100644 index 00000000..ed872336 --- /dev/null +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/custom-schema-mapping-annotation.adoc @@ -0,0 +1,13 @@ +== Type mapping annotation + +Another option for specifying default schema information to use for a particular message type is to mark the message class with the `@PulsarMessage` annotation. +The schema info can be specified via the `schemaType` attribute on the annotation. + +The following example configures the system to use JSON as the default schema when producing or consuming messages of type `Foo`: + +[source,java,indent=0,subs="verbatim"] +---- +@PulsarMessage(schemaType = SchemaType.JSON) +record Foo(String value) { +} +---- diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/custom-schema-mapping.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/custom-schema-mapping.adoc index 3175ee85..08b9489c 100644 --- a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/custom-schema-mapping.adoc +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/custom-schema-mapping.adoc @@ -34,16 +34,3 @@ public SchemaResolverCustomizer schemaResolverCustomizer( } } ---- - -==== Type mapping annotation -Another option for specifying default schema information to use for a particular message type is to mark the message class with the `@PulsarMessage` annotation. -The schema info can be specified via the `schemaType` attribute on the annotation. - -The following example configures the system to use JSON as the default schema when producing or consuming messages of type `Foo`: - -[source,java,indent=0,subs="verbatim"] ----- -@PulsarMessage(schemaType = SchemaType.JSON) -record Foo(String value) { -} ----- diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/schema-info-listener.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/schema-info-listener.adoc index bf8e7f7e..8a9198e4 100644 --- a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/schema-info-listener.adoc +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/schema-info-listener.adoc @@ -10,6 +10,9 @@ This removes the need to set the schema on the listener as the framework consult include::custom-schema-mapping.adoc[] +[[listener-default-schema-annotation]] +include::custom-schema-mapping-annotation.adoc[leveloffset=+2] + 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/antora/modules/ROOT/pages/reference/schema-info/schema-info-template.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/schema-info-template.adoc index 6b607736..91949297 100644 --- a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/schema-info-template.adoc +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/schema-info/schema-info-template.adoc @@ -13,8 +13,12 @@ This removes the need to specify the schema as the framework consults the resolv include::custom-schema-mapping.adoc[] +[[template-default-schema-annotation]] +include::custom-schema-mapping-annotation.adoc[leveloffset=+2] + With this configuration in place, there is no need to set specify the schema on send operations. +[[template-auto-produce]] === Producing with AUTO_SCHEMA If there is no chance to know the type of schema of a Pulsar topic in advance, you can use an {apache-pulsar-docs}/schema-get-started/#auto_produce[AUTO_PRODUCE] schema to publish a raw JSON or Avro payload as a `byte[]` safely. diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/topic-resolution.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/topic-resolution.adoc index 6ee3630c..4f4f9049 100644 --- a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/topic-resolution.adoc +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/reference/topic-resolution.adoc @@ -34,6 +34,7 @@ NOTE: The `message-type` is the fully-qualified name of the message class. WARNING: If the message (or the first message of a `Publisher` input) is `null`, the framework won't be able to determine the topic from it. Another method shall be used to specify the topic if your application is likely to send `null` messages. +[[default-topic-via-annotation]] === Specified via annotation When no topic is passed into the API and there are no custom topic mappings configured, the system looks for a `@PulsarMessage` annotation on the class of the message being produced or consumed. diff --git a/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/whats-new.adoc b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/whats-new.adoc new file mode 100644 index 00000000..60013ea6 --- /dev/null +++ b/spring-pulsar-docs/src/main/antora/modules/ROOT/pages/whats-new.adoc @@ -0,0 +1,23 @@ += What's new? + +[[what-s-new-in-1-1-since-1-0]] +== What's New in 1.1 Since 1.0 +:page-section-summary-toc: 1 + +This section covers the changes made from version 1.0 to version 1.1. + +=== Auto Schema support +If there is no chance to know the schema of a Pulsar topic in advance, you can use AUTO Schemas to produce/consume generic records to/from brokers. +See xref:./reference/pulsar.adoc#template-auto-produce[Producing with AUTO_SCHEMA] and xref:./reference/pulsar.adoc#listener-auto-consume[Consuming with AUTO_SCHEMA] for more details. + +NOTE: While the above links focus on `PulsarTemplate` and `@PulsarListener`, this feature is also supported in `ReactivePulsarTemplate`, `@ReactivePulsarListener`, and `@PulsarReader`. +Details for each can be found in their respective section of this reference guide. + +=== Default topic/schema via message annotation +You can now mark a message class with `@PulsarMessage` to specify the xref:./reference/pulsar.adoc#default-topic-via-annotation[default topic] and/or xref:./reference/pulsar.adoc#listener-default-schema-annotation[default schema] to use when producing/consuming messages of that type. + +=== Remove checked exceptions +The APIs provided by the framework no longer throw the checked `PulsarClientException`, but rather the unchecked `PulsarException`. + +WARNING: If you were previously catching or rethrowing `PulsarClientException` just to appease the compiler and were not actually handling the exception, you can simply remove your `catch` or `throws` clause. +If you were actually handling the exception then you will need to replace `PulsarClientException` with `PulsarException` in your catch clause.