|
| 1 | += Getting started with the Starlight for RabbitMQ extension |
| 2 | + |
| 3 | +:description: Learn how to get started using the Starlight for RabbitMQ extension with Pulsar and get hands on by publishing and consuming messages from a topic. |
| 4 | +:title: Getting started with the Starlight for RabbitMQ extension |
| 5 | +:navtitle: Starlight for RabbitMQ |
| 6 | + |
| 7 | +Starlight for RabbitMQ acts as a proxy between your https://www.rabbitmq.com/[RabbitMQ^]{external-link-icon} application and https://pulsar.apache.org/[Apache Pulsar™^]{external-link-icon} cluster. It implements the AMQP 0.9.1 protocol used by RabbitMQ clients and translates AMQP frames and concepts to Pulsar ones. |
| 8 | + |
| 9 | +If source code is your thing, visit the https://github.com/datastax/starlight-for-rabbitmq[project's repo on GitHub^]{external-link-icon}. |
| 10 | + |
| 11 | +== Architecture reference |
| 12 | + |
| 13 | +If you would like to get deep into how Starlight for RabbitMQ works, xref:starlight-for-rabbitmq:ROOT:index.adoc[read the docs]. |
| 14 | + |
| 15 | +image:s4r-architecture.png[Starlight for RabbitMQ Architecture] |
| 16 | + |
| 17 | +== Establishing the RabbitMQ protocol handler |
| 18 | + |
| 19 | +Before you can use a RabbitMQ client to interact with your Pulsar cluster, you need the Starlight for RabbitMQ protocol handler installed in the cluster. Installation looks a bit different depending on where your Pulsar cluster is running. Choose the option that best fits your needs. |
| 20 | + |
| 21 | +[tabs] |
| 22 | +==== |
| 23 | +Astra Streaming:: |
| 24 | ++ |
| 25 | +-- |
| 26 | +If you want a working RabbitMQ extension as quickly as possible, this is your best bet. This is also a good option for those that already have a streaming tenant and are looking to extend it. |
| 27 | +
|
| 28 | +. Sign in to your Astra account and navigate to your streaming tenant. |
| 29 | ++ |
| 30 | +TIP: Don't have a streaming tenant? Follow our "xref:astra-streaming:getting-started:index.adoc[]" guide. |
| 31 | +
|
| 32 | +. Go to the "Connect" tab and choose the "RabbitMQ" option. |
| 33 | ++ |
| 34 | +image:astra-streaming-connect-rabbitmq.png[Astra Streaming connect RabbitMQ] |
| 35 | +
|
| 36 | +. You will see an "Enable RabbitMQ" button. Click to continue. |
| 37 | ++ |
| 38 | +image:enable-rabbitmq-button.png[Astra Streaming enable RabbitMQ] |
| 39 | +
|
| 40 | +. A message will let you know of the additions (and restrictions) that come with using Starlight for RabbitMQ. |
| 41 | +image:enable-rabbitmq-message.png[Astra Streaming enable RabbitMQ message] |
| 42 | +
|
| 43 | +. Click the "Enable RabbitMQ" button to confirm your understanding. |
| 44 | +
|
| 45 | +Your Astra Streaming tenant is ready for prime time! Continue to the next section of the guide to see it in action. |
| 46 | +-- |
| 47 | +Luna Streaming:: |
| 48 | ++ |
| 49 | +-- |
| 50 | +The Starlight for RabbitMQ extension is included in the `luna-streaming-all` image used to deploy a Luna cluster. The Luna helm chart makes deploying the Kafka extension quite easy. Follow the "xref:luna-streaming:components:starlight-for-rabbitmq.adoc[]" guide to create a simple Pulsar cluster with the Starlight for RabbitMQ extension ready for use. |
| 51 | +-- |
| 52 | +Self Managed:: |
| 53 | ++ |
| 54 | +-- |
| 55 | +Already got your own Pulsar Cluster? Or maybe your using a standalone cluster? Starlight for RabbitMQ can easily be a part of that cluster! Follow the "xref:starlight-for-rabbitmq:installation:getting-started.adoc[]" guide. |
| 56 | +-- |
| 57 | +==== |
| 58 | + |
| 59 | +== Messaging with Starlight for RabbitMQ |
| 60 | + |
| 61 | +Starlight for RabbitMQ supports quite a few different use cases. With a Pulsar cluster between publishers and consumers you can interchange the type of publisher and consumer to fit your needs. *The below examples are using an Astra Streaming tenant as the AMQP listener.* If you are using Luna or self-managed, switch the listener URL for your own. |
| 62 | + |
| 63 | +=== Retrieve RabbitMQ connection properties in Astra Streaming |
| 64 | + |
| 65 | +While on the "Connect" tab in the Astra Streaming portal, the "RabbitMQ" area will provide important connection information. You will need that to create a working RabbitMQ client or using the CLI. |
| 66 | + |
| 67 | +image:rabbitmq-client-settings.png[Astra Streaming RabbitMQ settings] |
| 68 | + |
| 69 | +TIP: While reviewing the RabbitMQ connection settings in the Astra portal, if you click the clipboard icon you will get those values as well as a working token to paste in code. |
| 70 | + |
| 71 | +=== Produce and consume a message |
| 72 | + |
| 73 | +[tabs] |
| 74 | +==== |
| 75 | +RabbitMQ Client (Java):: |
| 76 | ++ |
| 77 | +-- |
| 78 | +This example uses maven as the project structure. If you prefer gradle or another, this code should still be a good fit. |
| 79 | +
|
| 80 | +TIP: Visit our https://github.com/datastax/astra-streaming-examples[examples repo^]{external-link-icon} to see the complete source of this example. |
| 81 | +
|
| 82 | +. Create a new maven project. |
| 83 | ++ |
| 84 | +[source,shell] |
| 85 | +---- |
| 86 | +include::{astra-streaming-examples-repo}/java/starlight-for-rabbitmq/rabbitmq-client/create-project.sh[] |
| 87 | +---- |
| 88 | +
|
| 89 | +. Open the new project in your favorite IDE or text editor and add the Kafka client dependency to "pom.xml". |
| 90 | ++ |
| 91 | +[source,xml] |
| 92 | +---- |
| 93 | +<dependency> |
| 94 | + <groupId>com.rabbitmq</groupId> |
| 95 | + <artifactId>amqp-client</artifactId> |
| 96 | + <version>5.16.0</version> |
| 97 | +</dependency> |
| 98 | +---- |
| 99 | +
|
| 100 | +. 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. |
| 101 | ++ |
| 102 | +[source,java] |
| 103 | +---- |
| 104 | +include::{astra-streaming-examples-repo}/java/starlight-for-rabbitmq/rabbitmq-client/StarlightForRabbitMqClient/src/main/java/org/example/App.java[tag=init-app] |
| 105 | +---- |
| 106 | ++ |
| 107 | +NOTE: Don't worry if your editor shows errors, this isn't a complete program... yet. |
| 108 | +
|
| 109 | +. Bring in the following code to create a valid connection, channel, and queue that will be used by both the producer and consumer. |
| 110 | ++ |
| 111 | +[source,java] |
| 112 | +---- |
| 113 | +include::{astra-streaming-examples-repo}/java/starlight-for-rabbitmq/rabbitmq-client/StarlightForRabbitMqClient/src/main/java/org/example/App.java[tag=create-queue] |
| 114 | +---- |
| 115 | +
|
| 116 | +. Now paste the producer code into the file. This is a very simple flow that sends a single message and awaits acknowledgment. |
| 117 | ++ |
| 118 | +[source,java] |
| 119 | +---- |
| 120 | +include::{astra-streaming-examples-repo}/java/starlight-for-rabbitmq/rabbitmq-client/StarlightForRabbitMqClient/src/main/java/org/example/App.java[tag=build-producer] |
| 121 | +---- |
| 122 | +
|
| 123 | +. Paste the consumer code into the file. This creates a basic consumer with callback on message receipt. Because the consumer isn't a blocking thread, we'll sleep for a few seconds and let things process. |
| 124 | ++ |
| 125 | +[source,java] |
| 126 | +---- |
| 127 | +include::{astra-streaming-examples-repo}/java/starlight-for-rabbitmq/rabbitmq-client/StarlightForRabbitMqClient/src/main/java/org/example/App.java[tag=build-consumer] |
| 128 | +---- |
| 129 | +
|
| 130 | +. Now you should have a complete program. Let's see it in action! Build and run the jar with the following terminal commands. |
| 131 | ++ |
| 132 | +[source,shell] |
| 133 | +---- |
| 134 | +mvn clean package assembly:single |
| 135 | +java -jar target/StarlightForRabbitMqClient-1.0-SNAPSHOT-jar-with-dependencies.jar |
| 136 | +---- |
| 137 | +
|
| 138 | +. If all goes as it should your output will be similar to this: |
| 139 | ++ |
| 140 | +[source,shell] |
| 141 | +---- |
| 142 | +Sent 'Hello World!' |
| 143 | +Received 'Hello World!' |
| 144 | +---- |
| 145 | +
|
| 146 | +Congrats! You have just used the RabbitMQ client to send and receive messages in Pulsar. |
| 147 | +-- |
| 148 | +==== |
0 commit comments