Spring/spring-pulsar
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Editing pass (#199)

Browse Source 
for grammar, usage, voice, spelling, and tense.
Also added some cross-references and, per my conversation
with Chris Bono, removed some includes.

Co-authored-by: Jay Bryant <jbryant@vmware.com>
This commit is contained in:
Jay Bryant
2022-11-10 12:50:39 -06:00
committed by GitHub
parent 82815d9dc5
commit f03d55bc67
6 changed files with 323 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
spring-pulsar-docs/src/main/asciidoc/application-properties.adoc
View File

@@ -2,12 +2,12 @@
[[appendix.application-properties]]
= Application Properties
Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches.
You can specify various properties inside your `application.properties` file, inside your `application.yml` file, or as command line switches.
This appendix provides a list of Spring Pulsar properties and references to the underlying classes that consume them.
TIP: Spring Boot provides various conversion mechanism with advanced value formatting, make sure to review <<features#features.external-config.typesafe-configuration-properties.conversion, the properties conversion section>>.
TIP: Spring Boot provides various conversion mechanisms with advanced value formatting. See <<features#features.external-config.typesafe-configuration-properties.conversion, the properties conversion section>> for more detail.
NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list.
NOTE: Property contributions can come from additional jar files on your classpath, so this list is not exhaustive.
Also, you can define your own properties.
include::application-properties/pulsar-client.adoc[]

9
spring-pulsar-docs/src/main/asciidoc/authentication.adoc
View File

@@ -1,4 +1,4 @@
To connect to a Pulsar cluster requiring authentication, you need to set the `authPluginClassName` and any parameters required by the authentication plugin. The parameters can be set as a single JSON encoded string or as map of parameter names to parameter values.
To connect to a Pulsar cluster that requires authentication, you need to set the `authPluginClassName` and any parameters required by the authentication plugin. You can set the parameters as a single JSON-encoded string or as map of parameter names to parameter values. The following listings show both approaches:
[source,yaml,indent=0,role="primary"]
.[.small]#Map#
@@ -12,6 +12,7 @@ spring:
private-key: file:///Users/some-key.json
audience: urn:sn:acme:dev:my-instance
----
.[.small]#JSON encoded string#
[source,yaml,indent=0,role="secondary"]
----
@@ -22,9 +23,9 @@ spring:
auth-params: "{\"privateKey\":\"file:///Users/some-key.json\",\"issuerUrl\":\"https://auth.server.cloud/", \"audience\":\"urn:sn:acme:dev:my-instance"}"
----
TIP: Using a map is the recommended approach as it is less error-prone and easier to read
TIP: Using a map is the recommended approach as it is less error-prone and easier to read.
The following shows how to configure each of the supported authentication mechanisms.
The following listings show how to configure each of the supported authentication mechanisms.
[[Athenz]]
.[.underline]#Click ##here## for **Athenz**#
@@ -131,4 +132,4 @@ spring:
====
NOTE: [.small]#More information on each of the schemes and their required properties can be found in the official link:https://pulsar.apache.org/docs/security-overview#authentication-providers[Pulsar security] documentation.#
NOTE: You can find more information on each of the schemes and their required properties in the official link:https://pulsar.apache.org/docs/security-overview#authentication-providers[Pulsar security] documentation.

4
spring-pulsar-docs/src/main/asciidoc/index.adoc
View File

@@ -5,7 +5,7 @@
:numbered:
:icons: font
:hide-uri-scheme:
Soby Chacko; Chris Bono; Alexander Preuß
Soby Chacko; Chris Bono; Alexander Preuß; Jay Bryant
//ifdef::backend-html5[]
//*{project-version}*
@@ -28,7 +28,7 @@ include::preface.adoc[]
[[quick-intro]]
== Introduction
This first part of the reference documentation is a high-level quick-tour of Spring for Apache Pulsar.
This first part of the reference documentation is a high-level quick tour of Spring for Apache Pulsar.
include::quick-tour.adoc[]

4
spring-pulsar-docs/src/main/asciidoc/preface.adoc
View File

@@ -1,4 +1,4 @@
This project provides a basic Spring-friendly API for developing https://pulsar.apache.org/[Apache Pulsar] applications.
On a very high-level, Spring for Apache Pulsar provides a `PulsarTemplate` for publishing to a Pulsar topic and a `PulsarListener` annotation for consuming from it.
In addition, it also provides various convenient APIs for Spring developers to ramp up their development journey into Apache Pulsar.
On a very high level, Spring for Apache Pulsar provides a `PulsarTemplate` for publishing to a Pulsar topic and a `PulsarListener` annotation for consuming from a Pulsar topic.
In addition, it also provides various convenience APIs for Spring developers to ramp up their development journey into Apache Pulsar.

609
spring-pulsar-docs/src/main/asciidoc/pulsar.adoc
View File

File diff suppressed because it is too large Load Diff

40
spring-pulsar-docs/src/main/asciidoc/quick-tour.adoc
View File

@@ -3,7 +3,7 @@
:spring-pulsar-version: 0.1.0-SNAPSHOT
In this section, we will take a quick tour of Spring for Apache Pulsar.
In this section, we take a quick tour of Spring for Apache Pulsar.
==== Minimum Supported Versions
@@ -29,14 +29,14 @@ The minimum supported versions for the underlying libraries required by the fram
=== Quick Sample
In the following sample Spring Boot application, we show how to write a publisher and consumer using Spring for Apache Pulsar.
This is a complete application and does not require any additional configuration as long as you have Pulsar cluster running on the default location - `localhost:6650`.
In the following sample Spring Boot application, we show how to write a publisher and a consumer that use Spring for Apache Pulsar.
This is a complete application and does not require any additional configuration, as long as you have a Pulsar cluster running on the default location - `localhost:6650`.
NOTE: We recommend the usage of a Spring-Boot-First-Approach for Spring for Apache Pulsar based application as that simplifies things tremendously. To encourage this, a `spring-pulsar-spring-boot-starter` module is published that can easily be consumed by an application as a dependency.
NOTE: We recommend using a Spring-Boot-First approach for Spring for Apache Pulsar-based application, as that simplifies things tremendously. To do so, you can add the `spring-pulsar-spring-boot-starter` module as a dependency.
==== Dependencies
Spring Boot applications only need the `spring-pulsar-spring-boot-starter` dependency. The following shows how to define the dependency for Maven and Gradle, respectively:
Spring Boot applications need only the `spring-pulsar-spring-boot-starter` dependency. The following listings show how to define the dependency for Maven and Gradle, respectively:
[source,xml,indent=0,subs="verbatim,attributes",role="primary"]
.Maven
@@ -59,7 +59,7 @@ dependencies {
----
===== Non-GA Versions
Snapshot or Milestone versions of the dependency can be found on the Spring Artifactory repository. The following shows how to define the repositories for Maven and Gradle, respectively:
You can find snapshot or milestone versions of the dependency in the Spring Artifactory repository. The following listings show how to define the repositories for Maven and Gradle, respectively:
[source,xml,indent=0,subs="verbatim,attributes",role="primary"]
.Maven
@@ -96,6 +96,9 @@ repositories {
----
==== Application Code
The following listing shows the Spring Boot application case for the example:
[source,java,indent=0,pending-extract=true,subs="verbatim"]
----
@SpringBootApplication
@@ -117,30 +120,29 @@ public class PulsarBootHelloWorld {
}
----
Let us go through the higher-level details of this application quickly.
Later on in this documentation, we will see these components in much more detail.
Let us quickly go through the higher-level details of this application.
<<reference,Later in this documentation>>, we see these components in much more detail.
In the sample above, we are heavily relying on Spring Boot auto-configuration.
In the preceding sample, we heavily rely on Spring Boot auto-configuration.
Spring Boot auto-configures several components for our application.
It automatically provides a `PulsarClient` for the application which is used by both the producer and the consumer.
It automatically provides a `PulsarClient`, which is used by both the producer and the consumer, for the application.
`PulsarTemplate` also is auto-configured by Spring Boot which we inject in the application and start sending records to a Pulsar topic.
Spring Boot also auto-configures `PulsarTemplate`, which we inject in the application and start sending records to a Pulsar topic.
The application sends messages to a topic named `hello-pulsar`.
Note that the application does not specify any schema information.
That is because Spring for Apache Pulsar library automatically infers the schema type from the type of the data that you are sending.
Note that the application does not specify any schema information, because Spring for Apache Pulsar library automatically infers the schema type from the type of the data that you send.
We use `PulsarListener` annotation to consume from the `hello-pulsar` topic where we publish the data.
`PulsarListener` is a convenient annotation that wraps the message listener container infrastructure in Spring for Apache Pulsar.
Behind the scenes, it creates a message listener container which creates and manages the Pulsar consumer.
We use the `PulsarListener` annotation to consume from the `hello-pulsar` topic where we publish the data.
`PulsarListener` is a convenience annotation that wraps the message listener container infrastructure in Spring for Apache Pulsar.
Behind the scenes, it creates a message listener container to create and manage the Pulsar consumer.
As with a regular Pulsar consumer, the default subscription type when using `PulsarListener` is the `Exclusive` mode.
As records are published in to the `hello-pulsar` topic, the `Pulsarlistener` consumes them and prints them on the console.
Here also, the framework infers the schema type used from the data type that the `PulsarListner` method uses as the payload - `String` in this case.
The framework also infers the schema type used from the data type that the `PulsarListner` method uses as the payload -- `String`, in this case.
=== Building the Project
If you have cloned the project locally, follow these steps in order to build the project from the soure code.
If you have cloned the project locally, follow these steps to build the project from the soure code.
Spring for Apache Pulsar uses Gradle as it's build tool. Run the following command to do a full build of the project:
Spring for Apache Pulsar uses Gradle as its build tool. Run the following command to do a full build of the project:
[indent=0]
----
./gradlew clean build