In this blog, which follows on from the Cloud Connectors in Payara Micro, we will explain the Microsoft Azure Service Bus connector and how to use it in Payara Server and Payara Micro (the Payara Platform).
A Quick Refresher on Terminology
- Messaging system → A messaging system is a system that handles platform-agnostic communication between machines. This is generally used for communicating between production systems (for example, health check messages), but can also be used for common use cases like chat applications and system integration.
- Broker → A broker is basically another word for a server in the context of messaging systems. It refers to a machine that stores all of the messages and distributes them to multiple clients.
What Are Microsoft Azure and the Azure Service Bus?
Microsoft Azure is a competing cloud computing platform along with the likes of Amazon Web Services and Google Cloud Platform. It provides cloud services from basic hosted virtual machines (IaaS) to hosted services for you to use out of the box (PaaS).
The Azure Service Bus is described by Microsoft in their FAQ as "an asynchronous messaging cloud platform that enables you to send data between decoupled systems". It's one of the PaaS services offered by Microsoft Azure that provides messaging to your hosted applications. The Service Bus provides multiple types of messaging for different use cases. These are all explained nicely in the fundamentals page: https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-fundamentals-hybrid-solutions.
Why Would I Use the Azure Service Bus?
The Service Bus is an integrated way to communicate between services hosted on Azure. The alternative is to host a broker manually on Azure which, although it would give you more flexibility in terms of which broker to choose, it would also add extra setup, costs, and maintenance.
Setting Up an Azure Service Bus
Firstly you'll need to create a Microsoft Azure account. This can be done from the portal: https://portal.azure.com/. At the time of writing this article, Microsoft is providing $200 of credit free of charge for new Azure accounts. This gives you more than enough to test the Azure platform fairly extensively.
Once you've created an account, you will be taken to the Azure dashboard. From here you'll want to go to 'All Resources' from the left bar:
Resources are the Azure term for the services they host for you, as well as any specific data like security keys. You won't have any resources to begin with, but you can begin with creating a Service Bus immediately. Click on 'Add' and search for 'Service Bus'. Click the Service Bus icon, and after clicking 'Create' from the information panel you'll see the following screen:
Enter a suitable Service Bus name, and create a new resource group to assign to it. A resource group defines a set of resources that are related. You can configure things like access control for the entire group. You can also deploy and update these resources together.
Click 'Create' when you're done. You'll be taken back to the resource list, where your new Service Bus should be listed. If it's not listed immediately, don't panic! Clicking the 'Refresh' button at the top of the table should make it appear.
Now we need a way to access this Service Bus. To do so, Azure uses access policies, which contain access keys. Azure creates a default access key for your new resource. To find it, click on the new resource and go to 'Shared access policies' → 'RootManageSharedAccessKey'. It will have a field called 'Primary Key' which, along with the name of the policy ("RootManageSharedAccessKey") are what we will use to access the Service Bus, so take a note of both. For the purposes of this guide, the default access policy is fine. For anything else I would suggest you create your own, which will add security as well as allow you to restrict people access to certain parts of the Service Bus. For example, some people may be allowed to listen but not post, and only a few people may be able to manage the Service Bus.
We now have a Service Bus, as well as access to it. But we'll need something to send and receive to/from. A single Service Bus can hold multiple queues and topics, which allows you to define the same users across multiple entities. We'll create a simple queue for this guide. Click on your custom Service Bus, and from there go to 'Queues'.
From here you can create and modify queues. Create a queue and configure the settings appropriately. You can configure the following settings:
- Maximum size → The maximum storage size of the queue.
- Message time to live → How long a message will stay in the queue before it expires and is removed.
- Lock duration → When an item is taken from the queue, it is marked as 'locked' until this duration expires. If the message was removed immediately, then a crashed server would have permanently deleted that message. The 'locked' value means that when this timer expires the item is allowed to be transferred to another worker.
- Move expired messages to the dead-letter subqueue → When a message's timeout is reached, instead of being deleted this message is moved to a different queue. This queue is found at the same URL as the main queue, but with /$DeadLetterQueue appended to the end.
- Enable duplicate detection → This means that duplicate items in the queue will be removed.
- Enable sessions → Means that receivers get allocated a session, and all messages belonging to a particular session are handled by the same broker. This allows the queue to do things like guarantee message ordering.
- Enable partitioning → Improves performance of the queue by storing messages across different partitions and only locking access to a specific partition. This gives the queue a higher throughput.
Click 'Create' on the queue. You now have all the information you need to connect to the queue, which means we can move onto creating an application to test the queue.
The bits of information you need to have a note of are:
- The queue name → You'll need the name of the queue for the application to send and receive to/from.
- The key name → This is the name of the key which is used for authentication purposes (The default key is called 'RootManageSharedAccessKey').
- The key contents → This is the long generated key which corresponds to the key above (In the 'Primary Key' field).
A Sample Microsoft Azure Service Bus Integration Application
This sample application will use the Cloud Connectors Suite. It will send a "Hello World!" message to the Service Bus queue, and then receive and print out each of these messages to the server log. These steps require a basic understanding of Java EE and Maven.
Firstly, create a new Maven project. The pom.xml will look like this:
Sending and Receiving Messages from the Service Bus
We can make two classes to show the Azure Service Bus usage: a sender class and a receiver class. The first class is the sender, which will send a "Hello World!" message every 3 seconds to the Azure Service Bus. The second class is the receiver, which will check for items to process every second, and then print out any messages it receives to the logs.
The sender class is shown below:
The other class is for receiving these messages by being declared as a Message Driven bean:
Now, proceed to build the application with the following command:
If the project fails to compile, make sure that your maven dependencies are all correct and you've not missed any bits from above.
Testing Azure Service Bus with Payara Micro
You should now have access to three files:
- The resource adapter (
- The application WAR for sending and receiving messages (
- The Payara Micro 181 JAR (target/payara-micro-5.181.jar).
All you need to run the application is the following command (run from the target/ directory).
Make sure that the deploy commands are in the correct order, or the deployment may fail. Once you've run this and Payara Micro has initialised, you should see messages similar to the following:
That's how to connect to the Azure Service Bus. This application could now be deployed to an instance also on Azure, and you'd have a backend that can connect to the message broker for fast, decoupled communication.