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

  1. In the Astra Streaming portal "Connect" tab, the "Pulsar" area provides important connection information.

    Astra Streaming kafka settings

  2. Scroll down to the "Tenant Details" area to find your Pulsar connection information.

    pulsar client settings

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.
  1. Create a new Maven project.

    mvn archetype:generate \
        -DgroupId=org.example \
        -DartifactId=StarlightForJMSClient \
        -DarchetypeArtifactId=maven-archetype-quickstart \
        -DinteractiveMode=false
    
    cd StarlightForJMSClient
  2. 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>
  3. 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.
  4. 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);
  5. 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
        }
      }
    }
  6. 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
  7. 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.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com