Package com.azure.messaging.servicebus.administration

package com.azure.messaging.servicebus.administration

The Azure Service Bus Administration client library allows for management of entities in their Service Bus namespace. It can be used to create, delete, update, or list queues, topics, rules, and subscriptions.

Microsoft Azure Service Bus is a fully managed enterprise integration message broker. Service Bus can decouple applications and services. Service Bus offers a reliable and secure platform for asynchronous transfer of data and state. Data is transferred between different applications and services using messages.

Key Concepts

  • Queue : Allows for the sending and receiving of messages, ordered first-in-first-out (FIFO). It is often used for point to point communication.
  • Topic : Allows for sending messages to multiple receivers, simultaneously. This is suited for publisher and subscriber scenarios.
  • Subscription: Receives messages from a topic. Each subscription is independent and receives a copy of every message sent to the topic. Each subscription has a filter. Filters, also known as rules, are applied to each message to determine whether they will be published to the subscription.
  • Rule Filters: A filter, associated with a subscription, that is tested against every message sent to a Service Bus topic. If the filter returns true, a copy of the message is published to that subscription. There are 3 types of filters: SQL filters, boolean filters, and correlation filters. More information can be found in: Topic filters.
  • Rule Actions : A modification applied to a Service Bus message when it matches the associated rule filter.

Getting Started

Service clients are the point of interaction for developers to use Azure Service Bus. ServiceBusAdministrationClient and ServiceBusAdministrationAsyncClient are the sync and async clients for managing entities in the Service Bus namespace.

The examples shown in this document use a credential object named DefaultAzureCredential for authentication, which is appropriate for most scenarios, including local development and production environments. Additionally, we recommend using managed identity for authentication in production environments. You can find more information on different ways of authenticating and their corresponding credential types in the Azure Identity documentation.

Creating clients

Sample: Create a ServiceBusAdministrationClient

The following code sample demonstrates the creation of the synchronous administration client.

 HttpLogOptions logOptions = new HttpLogOptions()
     .setLogLevel(HttpLogDetailLevel.HEADERS);

 // DefaultAzureCredential creates a credential based on the environment it is executed in.
 TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

 // 'fullyQualifiedNamespace' will look similar to "{your-namespace}.servicebus.windows.net"
 ServiceBusAdministrationClient client = new ServiceBusAdministrationClientBuilder()
     .credential(fullyQualifiedNamespace, tokenCredential)
     .httpLogOptions(logOptions)
     .buildClient();

Managing queues

Sample: Create a queue

The following code sample demonstrates the creation of a Service Bus queue with some configured options. If CreateQueueOptions are not passed in, default values are used to create the queue.

 CreateQueueOptions queueOptions = new CreateQueueOptions()
     .setLockDuration(Duration.ofMinutes(2))
     .setMaxDeliveryCount(15);

 QueueProperties queue = client.createQueue("my-new-queue", queueOptions);
 System.out.printf("Queue created. Name: %s. Lock Duration: %s.%n",
     queue.getName(), queue.getLockDuration());

Sample: Update a queue

The following code sample demonstrates updating a Service bus queue. Users should fetch the queue's properties, modify the properties, and then pass the object to update method.

 QueueProperties queue = client.getQueue("queue-that-exists");

 queue.setLockDuration(Duration.ofMinutes(3))
     .setMaxDeliveryCount(15)
     .setDeadLetteringOnMessageExpiration(true);

 QueueProperties updatedQueue = client.updateQueue(queue);

 System.out.printf("Queue updated. Name: %s. Lock duration: %s. Max delivery count: %s.%n",
     updatedQueue.getName(), updatedQueue.getLockDuration(), updatedQueue.getMaxDeliveryCount());

Managing topics and subscriptions

Sample: Create a topic, subscription, and rule

The following code sample demonstrates the creation of a Service Bus topic and subscription. The subscription filters for messages with a correlation id "emails" and has a "importance" property set to "high". Consequently, all high importance Service Bus messages will be delivered to the "high-importance-subscription" subscription. See Topic filters for additional information.

 String topicName = "my-new-topic";
 TopicProperties topic = client.createTopic(topicName);

 String subscriptionName = "high-importance-subscription";
 String ruleName = "important-emails-filter";
 CreateSubscriptionOptions subscriptionOptions = new CreateSubscriptionOptions()
     .setMaxDeliveryCount(15)
     .setLockDuration(Duration.ofMinutes(2));

 CorrelationRuleFilter ruleFilter = new CorrelationRuleFilter()
     .setCorrelationId("emails");
 ruleFilter.getProperties().put("importance", "high");

 CreateRuleOptions createRuleOptions = new CreateRuleOptions()
     .setFilter(ruleFilter);

 SubscriptionProperties subscription = client.createSubscription(topicName, subscriptionName, ruleName,
     subscriptionOptions, createRuleOptions);

 System.out.printf("Subscription created. Name: %s. Topic name: %s. Lock Duration: %s.%n",
     subscription.getSubscriptionName(), subscription.getTopicName(), subscription.getLockDuration());

Sample: Update a subscription

The following code sample demonstrates updating an existing subscription. Users should fetch the subscription, modify the properties, and pass that object into the update method.

 // To update the subscription we have to:
 // 1. Get the subscription info from the service.
 // 2. Update the SubscriptionProperties we want to change.
 // 3. Call the updateSubscription() with the updated object.
 SubscriptionProperties subscription = client.getSubscription("my-topic", "my-subscription");

 System.out.println("Original delivery count: " + subscription.getMaxDeliveryCount());

 // Updating it to a new value.
 subscription.setMaxDeliveryCount(5);

 // Persisting the updates to the subscription object.
 SubscriptionProperties updated = client.updateSubscription(subscription);

 System.out.printf("Subscription updated. Name: %s. Delivery count: %s.%n",
     updated.getSubscriptionName(), updated.getMaxDeliveryCount());