Getting started with Starlight for JMS

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.

Prerequisites

To get started you’ll just need a working Apache Pulsar cluster, with no bells or whistles required! 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 started quickly. If you want to dive deeper, read the documentation.

Astra Streaming
Luna Streaming
Self Managed

If you don’t have a tenant in Astra Streaming, follow our "Getting started with Astra Streaming" guide.

Follow the "Quick Start for Helm Chart installs" guide to get a cluster going.

Using a standalone cluster? The Starlight for JMS docs provide the "Starlight for JMS standalone quick start" guide.

Messaging with Starlight for JMS

Retrieve connection properties in Astra Streaming

In the Astra Streaming portal "Connect" tab, the "Pulsar" area provides important connection information.
Scroll down to the "Tenant Details" area to find your Pulsar connection information.

Produce and consume a message

This example uses Maven for the project structure. If you prefer Gradle or another tool, this code should still be a good fit.

Visit our examples repo↗ to see the complete source of this example.

Create a new Maven project.

mvn archetype:generate \
    -DgroupId=org.example \
    -DartifactId=StarlightForJMSClient \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DinteractiveMode=false

cd StarlightForJMSClient

Open the new project in your favorite IDE or text editor and add the jms dependency to "pom.xml".

<dependency>
  <groupId>com.datastax.oss</groupId>
  <artifactId>pulsar-jms-all</artifactId>
  <version>1.0.0</version>
</dependency>

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.

package org.example;

import com.datastax.oss.pulsar.jms.PulsarConnectionFactory;

import javax.jms.JMSContext;
import javax.jms.Message;
import javax.jms.MessageListener;
import javax.jms.Queue;
import java.util.HashMap;
import java.util.Map;

public class App
{
  private static String webServiceUrl = "<REPLACE_WITH_WEB_SERVICE_URL>";
  private static String brokerServiceUrl = "<REPLACE_WITH_BROKER_SERVICE_URL>";
  private static String pulsarToken = "<REPLACE_WITH_PULSAR_TOKEN>";
  private static String tenantName = "<REPLACE_WITH_TENANT_NAME>";
  private static final String namespace = "<REPLACE_WITH_NAMESPACE>";
  private static final String topicName = "<REPLACE_WITH_TOPIC_NAME>";
  private static final String topic = String.format("persistent://%s/%s/%s", tenantName,namespace,topicName);
  public static void main( String[] args ) throws Exception
  {

Don’t worry if your editor shows errors, this isn’t a complete program… yet.

Add the following code to build the configuration that will be used by both the producer and consumer.

    Map<String, Object> properties = new HashMap<>();
    properties.put("webServiceUrl",webServiceUrl);
    properties.put("brokerServiceUrl",brokerServiceUrl);
    properties.put("authPlugin","org.apache.pulsar.client.impl.auth.AuthenticationToken");
    properties.put("authParams",pulsarToken);

Add the following code into the file. 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. Finally, it produces a single message on the queue.

    try (PulsarConnectionFactory factory = new PulsarConnectionFactory(properties); ){
      JMSContext context = factory.createContext();
      Queue queue = context.createQueue(topic);

      context.createConsumer(queue).setMessageListener(new MessageListener() {
        @Override
        public void onMessage(Message message) {
          try {
            System.out.println("Received: " + message.getBody(String.class));
          } catch (Exception err) {
            err.printStackTrace();
          }
        }
      });

      String message = "Hello there!";
      System.out.println("Sending: "+message);
      context.createProducer().send(queue, message);

      Thread.sleep(4000); //wait for the message to be consumed
    }
  }
}

You now have a complete program, so let’s see it in action! Build and run the jar with the following terminal commands.
```
mvn clean package assembly:single
java -jar target/StarlightForJMSClient-1.0-SNAPSHOT-jar-with-dependencies.jar
```
If all goes as it should, your output will be similar to this:
```
Sending: Hello there!
Received: Hello there!
```

See how easy that was? You’re already an app modernization ninja!
Keep building those skills with the guides in the next section.

Getting started with Starlight for JMS

Prerequisites

Messaging with Starlight for JMS

Retrieve connection properties in Astra Streaming

Produce and consume a message

What’s next?