DOC-4604 Centralize Starlight for JMS quickstarts from Astra Streaming, Streaming Learning, and Luna Streaming (#18)

* bring over JMS, edit related links, headings

* unify nav, apply attributes

* navtitles and more attributes

* combine 2 jms quickstarts

* edit pom

* remove unnecessary build result example

* use a partial for common steps

* misc style cleanup

Author: aimurphy

antora.yml

@@ -5,10 +5,13 @@ start_page: 'index.adoc'
 
 nav:
 - modules/ROOT/nav.adoc
-- modules/jms-migration/nav.adoc
-- modules/examples/nav.adoc
-- modules/reference/nav.adoc
 
 asciidoc:
   attributes:
     jms_repo: 'https://github.com/datastax/pulsar-jms/'
+    pulsar-reg: 'Apache Pulsar(TM)'
+    pulsar: 'Apache Pulsar'
+    pulsar-short: 'Pulsar'
+    product: 'Starlight for JMS'
+    luna-streaming: 'Luna Streaming'
+    astra-streaming: 'Astra Streaming'

modules/ROOT/nav.adoc

@@ -1,2 +1,12 @@
-* {jms_repo}[Github repo]
-* xref:pulsar-jms-faq.adoc[]
+.Get started
+* {jms_repo}[Github repository]
+* xref:jms-migration:pulsar-jms-install.adoc[]
+* xref:jms-migration:pulsar-jms-quickstart-sa.adoc[]
+* xref:ROOT:pulsar-jms-faq.adoc[]
+
+.Configure
+* xref:reference:pulsar-jms-mappings.adoc[]
+* xref:examples:pulsar-jms-implementation.adoc[]
+* xref:examples:pulsar-jms-batch-ack.adoc[]
+* xref:examples:pulsar-jms-server-side-filters.adoc[]
+* xref:reference:pulsar-jms-reference.adoc[]

modules/ROOT/pages/index.adoc

@@ -1,27 +1,29 @@
-= About Starlight for JMS
-:navtitle: Starlight for JMS
+= About {product}
+:navtitle: {product}
 
-Starlight for JMS is the first highly compliant JMS implementation designed to run on a modern streaming platform. It allows enterprises to take advantage of the scalability and resiliency of a modern streaming platform to run their existing JMS applications. Because Apache Pulsar(TM) is open-source and cloud-native, Starlight for JMS enables enterprises to move their JMS applications to run on-premises and in any cloud environment.
+{jms_repo}[{product}] is the first highly compliant JMS implementation designed to run on a modern streaming platform.
+It allows enterprises to take advantage of the scalability and resiliency of a modern streaming platform to run their existing JMS applications. Because {pulsar-reg} is open-source and cloud-native, {product} enables enterprises to move their JMS applications to run on-premises and in any cloud environment.
 
 == Key Features
 
-Starlight for JMS key features include:
+{product} key features include:
 
 * *Blazing fast JMS performance*: Achieve 1 million JMS messages per second with 99 percentile publish to acknowledge latency of less than 10 ms.
 * *Drop-in replacement for existing JMS applications*: Supports JMS/Jakarta 2.0 and is backwards compatible with JMS 1.1. 100% pass rate on JMS compliance test for supported features.
-* *Horizontally scalable JMS*: Apache Pulsar is a horizontally scaled distributed streaming platform. You can scale up or down without operational hassles. Pulsar separates compute from storage, which means you can scale those dimensions independently, as required. Pulsar supports offloading old data to object storage for practically infinite storage capacity.
-* *Reduced total cost of ownership*: Because Apache Pulsar is natively multi-tenant and high performance, you can consolidate JMS applications spread across multiple legacy JMS brokers onto a single Apache Pulsar installation. And since Pulsar is easily horizontally scaled, you don’t need to overprovision.
-* *Future proof*: Apache Pulsar can support traditional messaging workloads, but it can also support modern streaming use cases such as log collection, microservices integration, event streaming, event sourcing. New workloads can run alongside Legacy JMS applications.
-* *Open source to avoid lock in*: Starlight for JMS and Apache Pulsar are 100% open source. You can run on-premise, in any cloud provider, or in Kubernetes.
-* *Adds message replay to JMS*: Apache Pulsar natively supports message retention and replay. This allows applications using Fast JMS for Apache Pulsar to travel back in time and replay previously consumed messages to recover from misconfiguration issues, recover from bugs in application code, and test new applications against real data.
-
-== What's next?
-
-* *xref:jms-migration:pulsar-jms-quickstart-sa.adoc[]*: Create a simple command line Java JMS client that connects to a local Pulsar installation.
-* *xref:streaming-learning:use-cases-architectures:starlight/jms/index.adoc[]*: Create a simple command line Java JMS client that connects to an Astra Streaming instance.
-* *xref:jms-migration:pulsar-jms-install.adoc[]*: Install Starlight for JMS in your own JMS project.
-* *xref:reference:pulsar-jms-mappings.adoc[]*: Understand Pulsar concepts in the context of JMS.
-* *xref:examples:pulsar-jms-implementation.adoc[]*: Understand key implementation details for Starlight for JMS.
-* *xref:pulsar-jms-faq.adoc[]*: Frequently asked questions about Starlight for JMS.
-* *xref:reference:pulsar-jms-reference.adoc[]*: Starlight for JMS configuration reference.
-* *{jms_repo}[Starlight for JMS Github repo]*
+* *Horizontally scalable JMS*: {pulsar} is a horizontally scaled distributed streaming platform. You can scale up or down without operational hassles. {pulsar-short} separates compute from storage, which means you can scale those dimensions independently, as required. {pulsar-short} supports offloading old data to object storage for practically infinite storage capacity.
+* *Reduced total cost of ownership*: Because {pulsar} is natively multi-tenant and high performance, you can consolidate JMS applications spread across multiple legacy JMS brokers onto a single {pulsar} installation. And since {pulsar-short} is easily horizontally scaled, you don't need to overprovision.
+* *Future proof*: {pulsar} can support traditional messaging workloads, but it can also support modern streaming use cases such as log collection, microservices integration, event streaming, event sourcing. New workloads can run alongside Legacy JMS applications.
+* *Open source to avoid lock in*: {product} and {pulsar} are 100% open source. You can run on-premise, in any cloud provider, or in Kubernetes.
+* *Adds message replay to JMS*: {pulsar} natively supports message retention and replay. This allows applications using Fast JMS for {pulsar} to travel back in time and replay previously consumed messages to recover from misconfiguration issues, recover from bugs in application code, and test new applications against real data.
+
+== Get started with {product}
+
+* xref:jms-migration:pulsar-jms-quickstart-sa.adoc[]
+* xref:jms-migration:pulsar-jms-install.adoc[]
+* xref:ROOT:pulsar-jms-faq.adoc[]
+
+== Learn more about {product}
+
+* xref:reference:pulsar-jms-mappings.adoc[]
+* xref:examples:pulsar-jms-implementation.adoc[]
+* xref:reference:pulsar-jms-reference.adoc[]

modules/ROOT/pages/pulsar-jms-faq.adoc

@@ -1,17 +1,17 @@
-= Starlight for JMS FAQs
+= {product} FAQs
 :navtitle: FAQs
 
-Answers to the (arguably) most common Starlight for JMS questions.
+Answers to common {product} questions.
 
-== What is the pricing for Starlight for JMS?
+== What is the pricing for {product}?
 
-Starlight for JMS is open source and is included in https://www.ibm.com/docs/en/supportforpulsar[IBM Elite Support for Apache Pulsar].
+{product} is open source and is included in https://www.ibm.com/docs/en/supportforpulsar[IBM Elite Support for {pulsar}].
 
-== How is Starlight for JMS licensed?
+== How is {product} licensed?
 
-Starlight for JMS is licensed under https://www.apache.org/licenses/LICENSE-2.0.txt[Apache version 2.0].
+{product} is licensed under https://www.apache.org/licenses/LICENSE-2.0.txt[Apache version 2.0].
 
-== How can I use Starlight for JMS in a JakartaEE(R) or JavaEE(R) application?
+== How can I use {product} in a JakartaEE(R) or JavaEE(R) application?
 
 You can use the `resourceAdapter` {jms_repo}blob/master/resource-adapter[here].
 
@@ -24,7 +24,7 @@ In the tck-executor module you'll find:
 * The Java Code needed to initialize the TCK, `JNDIInitialContextFactory.java`.
 * The configuration file for the TCK runner, `ts.jte`.
 * A file that contains the excluded tests that cannot pass with this client, `ts.jtx`
-* Scripts to run Apache Pulsar 2.7.1, configure the Transaction Coordinator, and prepare for the execution of the TCK.
+* Scripts to run {pulsar} 2.7.1, configure the Transaction Coordinator, and prepare for the execution of the TCK.
 
 To build the package, run unit tests, and run the TCK:
 
@@ -40,7 +40,7 @@ To run only the TCK:
 mvn clean install -Prun-tck -am -DskipTests -pl tck-executor
 ----
 
-IMPORTANT: Globally unique subscription names are not supported so the corresponding tests are skipped.
+IMPORTANT: Globally unique subscription names aren't supported so the corresponding tests are skipped.
 
 == Where can I find additional integration examples?
 
@@ -50,9 +50,9 @@ We've provided the following integration examples:
 * {jms_repo}blob/master/examples/payara-micro[Payara Micro(R)]
 * {jms_repo}blob/master/resource-adapter-tests[Apache TomEE(R)]
 
-== How can I build Starlight for JMS from source?
+== How can I build {product} from source?
 
-If you'd like to fork or contribute to Starlight for JMS:
+If you'd like to fork or contribute to {product}:
 
 . Clone the git repo:
 +
@@ -72,13 +72,3 @@ mvn clean install
 
 Refer to the https://jakarta.ee/specifications/messaging/2.0/[official JMS documentation] in order to learn about JMS.
 This https://javaee.github.io/jms-spec/[website] is useful as well as it contains the former JMS 2.0 specifications before the Jakarta transition.
-
-== What's next?
-
-* *xref:jms-migration:pulsar-jms-quickstart-sa.adoc[]*: Create a simple command line Java JMS client that connects to a local Pulsar installation.
-* *xref:streaming-learning:use-cases-architectures:starlight/jms/index.adoc[]*: Create a simple command line Java JMS client that connects to an Astra Streaming instance.
-* *xref:jms-migration:pulsar-jms-install.adoc[]*: Install Starlight for JMS in your own JMS project.
-* *xref:reference:pulsar-jms-mappings.adoc[]*: Understand Pulsar concepts in the context of JMS.
-* *xref:examples:pulsar-jms-implementation.adoc[]*: Understand key implementation details for Starlight for JMS.
-* *xref:reference:pulsar-jms-reference.adoc[]*: Starlight for JMS configuration reference.
-* *{jms_repo}[Starlight for JMS Github repo]*

modules/ROOT/partials/jms-quickstart-create-project.adoc

@@ -0,0 +1,80 @@
+. Create a new Maven project:
++
+[source,bash]
+----
+mvn archetype:generate \
+    -DgroupId=org.example \
+    -DartifactId=StarlightForJMSClient \
+    -DarchetypeArtifactId=maven-archetype-quickstart \
+    -DinteractiveMode=false
+----
+
+. Change to the new project directory:
++
+[source,bash]
+----
+cd StarlightForJMSClient
+----
+
+. Open the project in your IDE, and then add the {product} dependency to the `pom.xml` file.
++
+This quickstart uses the `pulsar-jms-all` package, which is a fat JAR file that includes all dependencies.
+{company} recommends using the {jms_repo}releases[latest stable release].
++
+.pom.xml
+[source,xml]
+----
+  <dependencies>
+    <dependency>
+      <groupId>com.datastax.oss</groupId>
+      <artifactId>pulsar-jms-all</artifactId>
+      <version>3.2.0</version>
+    </dependency>
+  </dependencies>
+----
+
+. Set the compiler source and target according to your Java version:
++
+.pom.xml
+[source,xml]
+----
+  <properties>
+    <maven.compiler.source>11</maven.compiler.source>
+    <maven.compiler.target>11</maven.compiler.target>
+  </properties>
+----
+
+. For this quickstart, include the following plugin configuration in the `build` section:
++
+* **`<artifactId>maven-assembly-plugin</artifactId>`**: The Maven Assembly Plugin that is used to compile a JAR file with all dependencies included.
+* **`<descriptorRef>jar-with-dependencies</descriptorRef>`**: An additional descriptor appended to the compiled JAR file name.
+* **`<mainClass>org.example.App</mainClass>`**: The default package and class so you can run the compiled JAR file without any additional specifications.
++
+.pom.xml
+[source,xml]
+----
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <configuration>
+          <descriptorRefs>
+            <descriptorRef>jar-with-dependencies</descriptorRef>
+          </descriptorRefs>
+          <archive>
+            <manifest>
+              <mainClass>org.example.App</mainClass>
+            </manifest>
+          </archive>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+----
+
+. In your Maven project, create an `example` subdirectory at `/src/main/java/org`:
++
+[source,bash]
+----
+mkdir -p /src/main/java/org/example
+----

modules/examples/nav.adoc

@@ -1,27 +1,34 @@
-= Batch index acknowledgement
+= Use batch index acknowledgement with {product}
+:navtitle: Use batch index acknowledgement
 
-Starlight for JMS improves acknowledgement of batched messages by supporting the tracking of 'ack' status by *batch index*. +
+{product} improves acknowledgement of batched messages by supporting the tracking of 'ack' status by batch index.
 
-By default, filtering works on the *entry* level in Pulsar. An *entry* is a *single message* or a *single batch of messages*. The client will not filter out a few messages in a batch; it either passes completely or fails completely. +
+By default, filtering works on the entry level in {pulsar-short}.
+An _entry_ is a single message, or a single batch of messages.
+The client cannot selectively filter messages in a batch; it either passes completely or fails completely.
 
-With *batch index acknowledgement*, when the broker dispatches messages, it will carry the batch index that has been acknowledged. The client will filter out batch indexes that have been acked. +
+With batch index acknowledgement, when the broker dispatches messages, it carries the batch index that has been acknowledged.
+Then, the client filters out batch indexes that have been acknowledged.
+Finally, the client sends the batch index acknowledgement information to the broker so the broker can maintain the batch index acknowledgement status.
 
-The client sends the batch index ack information to the broker, so the broker can maintain the batch index ack status. +
-
-This approach requires cooperation between the client and broker, so we must modify both `broker.conf` and the `consumerConfig` JMS client property to enable batch acknowledgement. +
-
-DataStax *strongly recommends* these configurations for increased efficiency, whether using *broker-side* or *client-side* selectors.
+[TIP]
+====
+{company} strongly recommends using batch index acknowledgement for increased efficiency, whether using broker-side or client-side selectors.
+====
 
 == Enable batch index acknowledgement
 
-. Add the configuration property `acknowledgmentAtBatchIndexLevelEnabled=true` to `broker.conf`:
+Batch index acknowledgement requires cooperation between the client and broker.
+You must modify both `broker.conf` and the `consumerConfig` JMS client property to enable batch acknowledgement:
+
+. In your `broker.conf` file, add the configuration property `acknowledgmentAtBatchIndexLevelEnabled` and set it to `true`:
 +
-[source,java]
+[source,conf]
 ----
 acknowledgmentAtBatchIndexLevelEnabled=true
 ----
 
-. Set the `consumerConfig` property on the JMS client by adding `consumerConfig.put("batchIndexAckEnabled", true);` to `consumerConfig` in the ConnectionFactory configuration:
+. In your Java project, set the `consumerConfig` property on the JMS client by adding `consumerConfig.put("batchIndexAckEnabled", true);` to `consumerConfig` in the `ConnectionFactory` configuration:
 +
 [source,java]
 ----
@@ -33,10 +40,7 @@ acknowledgmentAtBatchIndexLevelEnabled=true
     try (PulsarConnectionFactory factory = new PulsarConnectionFactory(properties));
 ----
 
-== What's next?
-
-For more on *server-side filtering*, see xref:pulsar-jms-server-side-filters.adoc[Server side filters]. +
-For more on acknowledgements in Starlight for JMS, see xref:reference:pulsar-jms-mappings.adoc#consumer-mappings[Consumer Mappings].
-
-
+== See also
 
+* xref:pulsar-jms-server-side-filters.adoc[]
+* xref:reference:pulsar-jms-mappings.adoc#consumer-mappings[Consumer mappings]