Azure Service Bus Cloud Connector

The Microsoft Azure Service Bus allows code that runs both outside and inside Azure to communicate with Azure.

Versioning

The tags below are for the Cloud Connectors repository. You should use the one corresponding to the Jakarta version you require.

0.8.0: Azure Service Bus Connector using JakartaEE 8 and the javax namespace
AzureServiceBus-1.0.0: Azure Service Bus Connector using JakartaEE 10 and the jakarta namespace

Usage

If you have selected to use Azure Service Bus Connector 1.0.0, replace all occurunces of 0.8.0 with 1.0.0 for the following example.

In order to connect to Azure, the azure-sb-rar-0.8.0.rar has to be deployed as shown in the Installing a connector section of the Cloud Connectors overview.

In order to make use of this connector in an application, the following maven dependency is needed:

<dependency>
  <groupId>fish.payara.cloud.connectors</groupId>
  <artifactId>azure-sb-jca-api</artifactId>
  <version>0.8.0</version>
  <type>jar</type>
  <scope>provided</scope>
</dependency>

Note that this dependency have scope provided since the types within this dependency are globally available to every application deployed to Payara Micro after the azure-sb-rar-0.8.0.rar was deployed.

Sending messages

Sending messages to Azure can be done via the JCA and an Azure specific API. In order to start using this API to send messages, a resource has to be defined via the JCA API; a connection factory.

The connection factory has to be given a name, which can be any name that is valid for JNDI. The java:app namespace is typically recommended to be used. The type of the connection factory to be used for the Azure Service Bus is fish.payara.cloud.connectors.azuresb.api.AzureSBConnectionFactory, and we have to specify the resource adapter name which is here AzureSBRAR-0.1.0-SNAPSHOT.

Finally the Azure credentials have to be specified.

The following gives an example:

@ConnectionFactoryDefinition (
  name = "java:app/azuresb/factory",
  interfaceName = "fish.payara.cloud.connectors.azuresb.api.AzureSBConnectionFactory",
  resourceAdapter = "azure-sb-rar-0.8.0"
  properties = {"nameSpace=payara", "sasKeyName=RootManageSharedAccessKey", "sasKey=someKey"}
)

With the above shown definition in place the following code shows an example of sending a message:

@Singleton
@Startup
public class SendAzureMessage {

  @Resource(lookup = "java:app/azuresb/factory")
  private AzureSBConnectionFactory factory;

  @PostConstruct
  public void init() {
    try (AzureSBConnection connection = factory.createConnection()) {
        connection.sendMessage("testq", new BrokeredMessage("Hello World"));
    }
    catch (Exception ex) {
    }
  }
}

Receiving messages

Messages can be received from Azure by creating an MDB (Message Driven Bean) that implements the fish.payara.cloud.connectors.azuresb.api.AzureSBListener marker interface and has a single method annotated with @OnAzureSBMessage and the method signature void method(BrokeredMessage message).

The following gives an example:

@MessageDriven(activationConfig = {
 @ActivationConfigProperty(propertyName = "nameSpace", propertyValue = "payara"),
 @ActivationConfigProperty(propertyName = "sasKeyName", propertyValue = "RootManageSharedAccessKey"),
 @ActivationConfigProperty(propertyName = "sasKey", propertyValue = "someKey"),
 @ActivationConfigProperty(propertyName = "queueName", propertyValue = "testq")
})
public class ReceiveAzureMessage implements AzureSBListener {
    @OnAzureSBMessage
    public void receiveMessage(BrokeredMessage message) {
        // Handle message
    }
}

The full list of config properties is given below:

Config Property Name	Type	Default	Notes
sasKeyName	String	none	The SAS Key Name defined in your Service Bus namespace
sasKey	String	none	The SAS Key. Environment variable replacement can be used so that this is not exposed in the code
nameSpace	String	none	The Azure namespace of your Service Bus
queueName	String	none	The Queue Name (MDB property only)
initialPollDelay	Integer	1	The Initial Poll Delay (in seconds) before the Adapter starts polling for messages after deployment (MDB Property Only)
pollInterval	Integer	1	The Poll interval (in seconds). This is how often the MDB polls for new messages (MDB Property Only)
pollTimeout	Integer	1	The Poll Timeout (in seconds). This is how long the MDB should wait for messages in a single poll (MDB Property Only)

Config Property Name

Type

Default

Notes

sasKeyName

String

none

The SAS Key Name defined in your Service Bus namespace

sasKey

String

none

The SAS Key. Environment variable replacement can be used so that this is not exposed in the code

nameSpace

String

none

The Azure namespace of your Service Bus

queueName

String

none

The Queue Name (MDB property only)

initialPollDelay

Integer

The Initial Poll Delay (in seconds) before the Adapter starts polling for messages after deployment (MDB Property Only)

pollInterval

Integer

The Poll interval (in seconds). This is how often the MDB polls for new messages (MDB Property Only)

pollTimeout

Integer

The Poll Timeout (in seconds). This is how long the MDB should wait for messages in a single poll (MDB Property Only)