|
| 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. This guide will get you up and running with a simple Java JMS client that can talk to an Apache Pulsar™ streaming instance. |
| 10 | + |
| 11 | +== Getting started |
| 12 | + |
| 13 | +To get started you will need a working Apache Pulsar cluster. There's really no bells or whistles that need to be added. You'll need access to the Cluster's admin port 8080 and the binary port 6650. For this guide, we will use Astra Streaming to get going quickly. |
| 14 | + |
| 15 | +[tabs] |
| 16 | +==== |
| 17 | +Astra Streaming:: |
| 18 | ++ |
| 19 | +-- |
| 20 | +
|
| 21 | +If you don't have a tenant in Astra Streaming, follow our "xref:astra-streaming:getting-started:index.adoc[]" guide. |
| 22 | +
|
| 23 | +-- |
| 24 | +Luna Streaming:: |
| 25 | ++ |
| 26 | +-- |
| 27 | +Follow the "xref:luna-streaming:install-upgrade:quickstart-helm-installs.adoc[]" guide to get a cluster going. |
| 28 | +-- |
| 29 | +Self Managed:: |
| 30 | ++ |
| 31 | +-- |
| 32 | +Using a standalone cluster? The Starlight for JMS docs provide the "xref:starlight-for-jms:jms-migration:pulsar-jms-quickstart-sa.adoc[]" guide. |
| 33 | +-- |
| 34 | +==== |
| 35 | + |
| 36 | +== Messaging with Starlight for JMS |
| 37 | + |
| 38 | +=== Retrieve connection properties in Astra Streaming |
| 39 | + |
| 40 | +. While on the "Connect" tab in the Astra Streaming portal, the "pulsar" area will provide important connection information. |
| 41 | ++ |
| 42 | +image:astra-streaming-connect-pulsar.png[Astra Streaming kafka settings] |
| 43 | + |
| 44 | +. Scroll down and find the "Tenant Details" area to find your Pulsar connection information. |
| 45 | ++ |
| 46 | +image:pulsar-client-settings.png[] |
| 47 | + |
| 48 | +=== Produce and consume a message |
| 49 | + |
| 50 | +This example uses maven as the project structure. If you prefer gradle or another, this code should still be a good fit. |
| 51 | + |
| 52 | +TIP: Visit our https://github.com/datastax/astra-streaming-examples[examples repo^]{external-link-icon} to see the complete source of this example. |
| 53 | + |
| 54 | +. Create a new maven project. |
| 55 | ++ |
| 56 | +[source,shell] |
| 57 | +---- |
| 58 | +include::{astra-streaming-examples-repo}/java/starlight-for-jms/create-project.sh[] |
| 59 | +---- |
| 60 | + |
| 61 | +. Open the new project in your favorite IDE or text editor and add the jms dependency to "pom.xml". |
| 62 | ++ |
| 63 | +[source,xml] |
| 64 | +---- |
| 65 | +<dependency> |
| 66 | + <groupId>com.datastax.oss</groupId> |
| 67 | + <artifactId>pulsar-jms-all</artifactId> |
| 68 | + <version>1.0.0</version> |
| 69 | +</dependency> |
| 70 | +---- |
| 71 | + |
| 72 | +. 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. |
| 73 | ++ |
| 74 | +[source,java] |
| 75 | +---- |
| 76 | +include::{astra-streaming-examples-repo}/java/starlight-for-jms/StarlightForJMSClient/src/main/java/org/example/App.java[tag=init-app] |
| 77 | +---- |
| 78 | ++ |
| 79 | +NOTE: Don't worry if your editor shows errors, this isn't a complete program... yet. |
| 80 | + |
| 81 | +. Bring in the following code to build the configuration that will be used by both the producer and consumer. |
| 82 | ++ |
| 83 | +[source,java] |
| 84 | +---- |
| 85 | +include::{astra-streaming-examples-repo}/java/starlight-for-jms/StarlightForJMSClient/src/main/java/org/example/App.java[tag=build-config] |
| 86 | +---- |
| 87 | + |
| 88 | +. Now paste the following into the file. This is a very simple 'PulsarConnectionFactory' that first creates a jms queue using the full Pulsar topic address. Then it creates a message listener callback function that watches the queue, and finally it produces a single message on the queue. |
| 89 | ++ |
| 90 | +[source,java] |
| 91 | +---- |
| 92 | +include::{astra-streaming-examples-repo}/java/starlight-for-jms/StarlightForJMSClient/src/main/java/org/example/App.java[tag=build-factory] |
| 93 | +---- |
| 94 | + |
| 95 | +. Now you should have a complete program. Let's see it in action! Build and run the jar with the following terminal commands. |
| 96 | ++ |
| 97 | +[source,shell] |
| 98 | +---- |
| 99 | +mvn clean package assembly:single |
| 100 | +java -jar target/StarlightForJMSClient-1.0-SNAPSHOT-jar-with-dependencies.jar |
| 101 | +---- |
| 102 | + |
| 103 | +. If all goes as it should your output will be similar to this: |
| 104 | ++ |
| 105 | +[source,shell] |
| 106 | +---- |
| 107 | +Sending: Hello there! |
| 108 | +Received: Hello there! |
| 109 | +---- |
| 110 | + |
| 111 | +See how easy that was! You're an app modernization ninja all ready. Let's continue building those skills with a few other guides. |
| 112 | + |
| 113 | +* xref:starlight-for-jms:examples:pulsar-jms-implementation.adoc[] |
| 114 | +* xref:starlight-for-jms:reference:pulsar-jms-mappings.adoc[] |
| 115 | +* xref:starlight-for-jms:reference:pulsar-jms-reference.adoc[] |
0 commit comments