|
| 1 | += Getting started with Starlight for JMS |
| 2 | + |
| 3 | +:description: Learn how to get started using the Starlight for JMS API and get hands on with a producer and consumer interacting with a topic. |
| 4 | +:title: Getting started with the Starlight for JMS |
| 5 | +:navtitle: Starlight for JMS |
| 6 | +:page-aliases: docs@starlight-jms::pulsar-jms-quickstart-astra.adoc,starlight-jms:streaming-learning:use-cases-architectures:starlight/jms/index.adoc |
| 7 | +:page-tag: starlight-jms,dev,quickstart,pulsar,jms |
| 8 | + |
| 9 | +Starlight for JMS is a highly compliant JMS implementation designed to run on a modern streaming platform. |
| 10 | +This guide will get you up and running with a simple Java JMS client that can talk to an Apache Pulsar™ streaming instance. |
| 11 | + |
| 12 | +== Prerequisites |
| 13 | + |
| 14 | +To get started you'll just need a working Apache Pulsar cluster, with no bells or whistles requiured! |
| 15 | +You'll need access to the cluster's admin port 8080 and the binary port 6650. |
| 16 | +For this guide, we will use Astra Streaming to get started quickly. If you want to dive deeper, xref:starlight-for-jms:ROOT:index.adoc[read the documentation]. |
| 17 | + |
| 18 | +[tabs] |
| 19 | +==== |
| 20 | +Astra Streaming:: |
| 21 | ++ |
| 22 | +-- |
| 23 | +
|
| 24 | +If you don't have a tenant in Astra Streaming, follow our "xref:astra-streaming:getting-started:index.adoc[]" guide. |
| 25 | +
|
| 26 | +-- |
| 27 | +Luna Streaming:: |
| 28 | ++ |
| 29 | +-- |
| 30 | +Follow the "xref:luna-streaming:install-upgrade:quickstart-helm-installs.adoc[]" guide to get a cluster going. |
| 31 | +-- |
| 32 | +Self Managed:: |
| 33 | ++ |
| 34 | +-- |
| 35 | +Using a standalone cluster? The Starlight for JMS docs provide the "xref:starlight-for-jms:jms-migration:pulsar-jms-quickstart-sa.adoc[]" guide. |
| 36 | +-- |
| 37 | +==== |
| 38 | + |
| 39 | +== Messaging with Starlight for JMS |
| 40 | + |
| 41 | +=== Retrieve connection properties in Astra Streaming |
| 42 | + |
| 43 | +. In the Astra Streaming portal "Connect" tab, the "Pulsar" area provides important connection information. |
| 44 | ++ |
| 45 | +image:astra-streaming-connect-pulsar.png[Astra Streaming kafka settings] |
| 46 | + |
| 47 | +. Scroll down to the "Tenant Details" area to find your Pulsar connection information. |
| 48 | ++ |
| 49 | +image:pulsar-client-settings.png[] |
| 50 | + |
| 51 | +=== Produce and consume a message |
| 52 | + |
| 53 | +This example uses Maven for the project structure. |
| 54 | +If you prefer Gradle or another tool, this code should still be a good fit. |
| 55 | + |
| 56 | +TIP: Visit our https://github.com/datastax/astra-streaming-examples[examples repo^]{external-link-icon} to see the complete source of this example. |
| 57 | + |
| 58 | +. Create a new Maven project. |
| 59 | ++ |
| 60 | +[source,shell] |
| 61 | +---- |
| 62 | +include::{astra-streaming-examples-repo}/java/starlight-for-jms/create-project.sh[] |
| 63 | +---- |
| 64 | + |
| 65 | +. Open the new project in your favorite IDE or text editor and add the jms dependency to "pom.xml". |
| 66 | ++ |
| 67 | +[source,xml] |
| 68 | +---- |
| 69 | +<dependency> |
| 70 | + <groupId>com.datastax.oss</groupId> |
| 71 | + <artifactId>pulsar-jms-all</artifactId> |
| 72 | + <version>1.0.0</version> |
| 73 | +</dependency> |
| 74 | +---- |
| 75 | + |
| 76 | +. Open the file "src/main/java/org/example/App.java" and replace the entire contents with the below code. Notice there are class variables that need replacing. Apply the values previously retrieved in Astra Streaming. |
| 77 | ++ |
| 78 | +[source,java] |
| 79 | +---- |
| 80 | +include::{astra-streaming-examples-repo}/java/starlight-for-jms/StarlightForJMSClient/src/main/java/org/example/App.java[tag=init-app] |
| 81 | +---- |
| 82 | ++ |
| 83 | +NOTE: Don't worry if your editor shows errors, this isn't a complete program... yet. |
| 84 | + |
| 85 | +. Add the following code to build the configuration that will be used by both the producer and consumer. |
| 86 | ++ |
| 87 | +[source,java] |
| 88 | +---- |
| 89 | +include::{astra-streaming-examples-repo}/java/starlight-for-jms/StarlightForJMSClient/src/main/java/org/example/App.java[tag=build-config] |
| 90 | +---- |
| 91 | + |
| 92 | +. Add the following code into the file. |
| 93 | +This is a very simple 'PulsarConnectionFactory' that first creates a JMS queue using the full Pulsar topic address, then creates a message listener callback function that watches the queue. |
| 94 | +Finally, it produces a single message on the queue. |
| 95 | ++ |
| 96 | +[source,java] |
| 97 | +---- |
| 98 | +include::{astra-streaming-examples-repo}/java/starlight-for-jms/StarlightForJMSClient/src/main/java/org/example/App.java[tag=build-factory] |
| 99 | +---- |
| 100 | + |
| 101 | +. You now have a complete program, so let's see it in action! Build and run the jar with the following terminal commands. |
| 102 | ++ |
| 103 | +[source,shell] |
| 104 | +---- |
| 105 | +mvn clean package assembly:single |
| 106 | +java -jar target/StarlightForJMSClient-1.0-SNAPSHOT-jar-with-dependencies.jar |
| 107 | +---- |
| 108 | + |
| 109 | +. If all goes as it should, your output will be similar to this: |
| 110 | ++ |
| 111 | +[source,shell] |
| 112 | +---- |
| 113 | +Sending: Hello there! |
| 114 | +Received: Hello there! |
| 115 | +---- |
| 116 | + |
| 117 | +See how easy that was? You're already an app modernization ninja! + |
| 118 | +Keep building those skills with the guides in the next section. |
| 119 | + |
| 120 | +== What's next? |
| 121 | + |
| 122 | +* xref:starlight-for-jms:examples:pulsar-jms-implementation.adoc[] |
| 123 | +* xref:starlight-for-jms:reference:pulsar-jms-mappings.adoc[] |
| 124 | +* xref:starlight-for-jms:reference:pulsar-jms-reference.adoc[] |
0 commit comments