ServiceBusClientBuilder (Azure SDK for Java Reference Documentation)

java.lang.Object
- com.azure.messaging.servicebus.ServiceBusClientBuilder

public final class ServiceBusClientBuilder
extends Object

The builder to create Service Bus clients:

Instantiate a synchronous sender

 // Retrieve 'connectionString' and 'queueName' from your configuration.
 ServiceBusClientBuilder builder = new ServiceBusClientBuilder()
     .connectionString(connectionString);
 ServiceBusSenderClient sender = builder
     .sender()
     .queueName(queueName)
     .buildClient();

Instantiate an asynchronous receiver

 // Retrieve 'connectionString', 'topicName' and 'subscriptionName' from your configuration.
 ServiceBusClientBuilder builder = new ServiceBusClientBuilder()
     .connectionString(connectionString);
 ServiceBusReceiverAsyncClient receiver = builder
     .receiver()
     .disableAutoComplete() // Allows user to take control of settling a message.
     .topicName(topicName)
     .subscriptionName(subscriptionName)
     .buildAsyncClient();

Instantiate an asynchronous session receiver

 // Retrieve 'connectionString', 'topicName' and 'subscriptionName' from your configuration.
 ServiceBusSessionReceiverAsyncClient sessionReceiver = new ServiceBusClientBuilder()
     .connectionString(connectionString)
     .sessionReceiver()
     .receiveMode(ServiceBusReceiveMode.PEEK_LOCK)
     .topicName(topicName)
     .subscriptionName(subscriptionName)
     .buildAsyncClient();
 
 // Receiving messages from the first available sessions. It waits up to the AmqpRetryOptions.getTryTimeout().
 // If no session is available within that operation timeout, it completes with an error. Otherwise, a receiver
 // is returned when a lock on the session is acquired.
 Mono<ServiceBusReceiverAsyncClient> receiverMono = sessionReceiver.acceptNextSession();
 
 Flux.usingWhen(receiverMono,
     receiver -> receiver.receiveMessages(),
     receiver -> Mono.fromRunnable(receiver::close))
     .subscribe(message -> System.out.println(message.getBody().toString()));

Instantiate the processor

 // Retrieve 'connectionString' and 'queueName' from your configuration.
 ServiceBusClientBuilder builder = new ServiceBusClientBuilder()
     .connectionString(connectionString);
 ServiceBusProcessorClient processor = builder
     .processor()
     .queueName(queueName)
     .processMessage(System.out::println)
     .processError(context -> System.err.println(context.getErrorSource()))
     .buildProcessorClient();

Sharing a connection between clients

The creation of physical connection to Service Bus requires resources. If your architecture allows, an application should share connection between clients which can be achieved by sharing the top level builder as shown below.

 // Retrieve 'connectionString' and 'queueName' from your configuration.
 // Create shared builder.
 ServiceBusClientBuilder sharedConnectionBuilder = new ServiceBusClientBuilder()
     .connectionString(connectionString);
 // Create receiver and sender which will share the connection.
 ServiceBusReceiverClient receiver = sharedConnectionBuilder
     .receiver()
     .queueName(queueName)
     .buildClient();
 ServiceBusSenderClient sender = sharedConnectionBuilder
     .sender()
     .queueName(queueName)
     .buildClient();

Clients for sending messages

Clients for receiving messages

Clients for receiving messages from a session-enabled Service Bus entity

Client for receiving messages using a callback-based processor

ServiceBusProcessorClient

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`class`	`ServiceBusClientBuilder.ServiceBusProcessorClientBuilder` Builder for creating `ServiceBusProcessorClient` to consume messages from a Service Bus entity.
`class`	`ServiceBusClientBuilder.ServiceBusReceiverClientBuilder` Builder for creating `ServiceBusReceiverClient` and `ServiceBusReceiverAsyncClient` to consume messages from Service Bus.
`class`	`ServiceBusClientBuilder.ServiceBusSenderClientBuilder` Builder for creating `ServiceBusSenderClient` and `ServiceBusSenderAsyncClient` to publish messages to Service Bus.
`class`	`ServiceBusClientBuilder.ServiceBusSessionProcessorClientBuilder` Builder for creating `ServiceBusProcessorClient` to consume messages from a session-based Service Bus entity.
`class`	`ServiceBusClientBuilder.ServiceBusSessionReceiverClientBuilder` Builder for creating `ServiceBusReceiverClient` and `ServiceBusReceiverAsyncClient` to consume messages from a session aware Service Bus entity.

Constructor Summary

Constructors
Constructor and Description

ServiceBusClientBuilder()
Creates a new instance with the default transport AmqpTransportType.AMQP.

Constructors
Constructor and Description
`ServiceBusClientBuilder()` Creates a new instance with the default transport `AmqpTransportType.AMQP`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ServiceBusClientBuilder`	`clientOptions(com.azure.core.util.ClientOptions clientOptions)` Sets the `ClientOptions` to be sent from the client built from this builder, enabling customization of certain properties, as well as support the addition of custom header information.
`ServiceBusClientBuilder`	`configuration(com.azure.core.util.Configuration configuration)` Sets the configuration store that is used during construction of the service client.
`ServiceBusClientBuilder`	`connectionString(String connectionString)` Sets the connection string for a Service Bus namespace or a specific Service Bus resource.
`ServiceBusClientBuilder`	`credential(String fullyQualifiedNamespace, com.azure.core.credential.AzureNamedKeyCredential credential)` Sets the credential with the shared access policies for the Service Bus resource.
`ServiceBusClientBuilder`	`credential(String fullyQualifiedNamespace, com.azure.core.credential.AzureSasCredential credential)` Sets the credential with Shared Access Signature for the Service Bus resource.
`ServiceBusClientBuilder`	`credential(String fullyQualifiedNamespace, com.azure.core.credential.TokenCredential credential)` Sets the credential by using a `TokenCredential` for the Service Bus resource.
`ServiceBusClientBuilder`	`enableCrossEntityTransactions()` Enable cross entity transaction on the connection to Service bus.
`ServiceBusClientBuilder.ServiceBusProcessorClientBuilder`	`processor()` A new instance of `ServiceBusClientBuilder.ServiceBusProcessorClientBuilder` used to configure `ServiceBusProcessorClient` instance.
`ServiceBusClientBuilder`	`proxyOptions(com.azure.core.amqp.ProxyOptions proxyOptions)` Sets the proxy configuration to use for `ServiceBusSenderAsyncClient`.
`ServiceBusClientBuilder.ServiceBusReceiverClientBuilder`	`receiver()` A new instance of `ServiceBusClientBuilder.ServiceBusReceiverClientBuilder` used to configure Service Bus message receivers.
`ServiceBusClientBuilder`	`retryOptions(com.azure.core.amqp.AmqpRetryOptions retryOptions)` Sets the retry options for Service Bus clients.
`ServiceBusClientBuilder.ServiceBusSenderClientBuilder`	`sender()` A new instance of `ServiceBusClientBuilder.ServiceBusSenderClientBuilder` used to configure Service Bus message senders.
`ServiceBusClientBuilder.ServiceBusSessionProcessorClientBuilder`	`sessionProcessor()` A new instance of `ServiceBusClientBuilder.ServiceBusSessionProcessorClientBuilder` used to configure a Service Bus processor instance that processes sessions.
`ServiceBusClientBuilder.ServiceBusSessionReceiverClientBuilder`	`sessionReceiver()` A new instance of `ServiceBusClientBuilder.ServiceBusSessionReceiverClientBuilder` used to configure session aware Service Bus message receivers.
`ServiceBusClientBuilder`	`transportType(com.azure.core.amqp.AmqpTransportType transportType)` Sets the transport type by which all the communication with Azure Service Bus occurs.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - ServiceBusClientBuilder
```
public ServiceBusClientBuilder()
```
    Creates a new instance with the default transport AmqpTransportType.AMQP.
- Method Detail
  - clientOptions
```
public ServiceBusClientBuilder clientOptions(com.azure.core.util.ClientOptions clientOptions)
```
    Sets the ClientOptions to be sent from the client built from this builder, enabling customization of certain properties, as well as support the addition of custom header information. Refer to the ClientOptions documentation for more information.
    
    Parameters:
    
    clientOptions - to be set on the client.
    
    Returns:
    
    The updated ServiceBusClientBuilder object.
  - connectionString
```
public ServiceBusClientBuilder connectionString(String connectionString)
```
    Sets the connection string for a Service Bus namespace or a specific Service Bus resource.
    
    Parameters:
    
    connectionString - Connection string for a Service Bus namespace or a specific Service Bus resource.
    
    Returns:
    
    The updated ServiceBusClientBuilder object.
  - enableCrossEntityTransactions
```
public ServiceBusClientBuilder enableCrossEntityTransactions()
```
    Enable cross entity transaction on the connection to Service bus. Use this feature only when your transaction scope spans across different Service Bus entities. This feature is achieved by routing all the messages through one 'send-via' entity on server side as explained next. Once clients are created for multiple entities, the first entity that an operation occurs on becomes the entity through which all subsequent sends will be routed through ('send-via' entity). This enables the service to perform a transaction that is meant to span multiple entities. This means that subsequent entities that perform their first operation need to either be senders, or if they are receivers they need to be on the same entity as the initial entity through which all sends are routed through (otherwise the service would not be able to ensure that the transaction is committed because it cannot route a receive operation through a different entity). For instance, if you have SenderA (For entity A) and ReceiverB (For entity B) that are created from a client with cross-entity transactions enabled, you would need to receive first with ReceiverB to allow this to work. If you first send to entity A, and then attempted to receive from entity B, an exception would be thrown.
    Avoid using non-transaction API on this client
    Since this feature will set up connection to Service Bus optimised to enable this feature. Once all the clients have been setup, the first receiver or sender used will initialize 'send-via' queue as a single message transfer entity. All the messages will flow via this queue. Thus this client is not suitable for any non-transaction API.
    When not to enable this feature
    If your transaction is involved in one Service bus entity only. For example you are receiving from one queue/subscription and you want to settle your own messages which are part of one transaction.
    
    Returns:
    
    The updated ServiceBusClientBuilder.ServiceBusSenderClientBuilder object.
    
    See Also:
    
    Service Bus transactions
  - configuration
```
public ServiceBusClientBuilder configuration(com.azure.core.util.Configuration configuration)
```
    Sets the configuration store that is used during construction of the service client. If not specified, the default configuration store is used to configure Service Bus clients. Use Configuration.NONE to bypass using configuration settings during construction.
    
    Parameters:
    
    configuration - The configuration store used to configure Service Bus clients.
    
    Returns:
    
    The updated ServiceBusClientBuilder object.
  - credential
```
public ServiceBusClientBuilder credential(String fullyQualifiedNamespace,
                                          com.azure.core.credential.TokenCredential credential)
```
    Sets the credential by using a TokenCredential for the Service Bus resource. azure-identity has multiple TokenCredential implementations that can be used to authenticate the access to the Service Bus resource.
    
    Parameters:
    
    fullyQualifiedNamespace - The fully-qualified namespace for the Service Bus.
    
    credential - The token credential to use for authentication. Access controls may be specified by the ServiceBus namespace or the requested Service Bus entity, depending on Azure configuration.
    
    Returns:
    
    The updated ServiceBusClientBuilder object.
  - credential
```
public ServiceBusClientBuilder credential(String fullyQualifiedNamespace,
                                          com.azure.core.credential.AzureNamedKeyCredential credential)
```
    Sets the credential with the shared access policies for the Service Bus resource. You can find the shared access policies on the azure portal or Azure CLI. For instance, on the portal, "Shared Access policies" has 'policy' and its 'Primary Key' and 'Secondary Key'. The 'name' attribute of the AzureNamedKeyCredential is the 'policy' on portal and the 'key' attribute can be either 'Primary Key' or 'Secondary Key'. This method and ServiceBusClientBuilder.connectionString(String) take the same information in different forms. But it allows you to update the name and key.
    
    Parameters:
    
    fullyQualifiedNamespace - The fully-qualified namespace for the Service Bus.
    
    credential - AzureNamedKeyCredential to be used for authentication.
    
    Returns:
    
    The updated ServiceBusClientBuilder object.
  - credential
```
public ServiceBusClientBuilder credential(String fullyQualifiedNamespace,
                                          com.azure.core.credential.AzureSasCredential credential)
```
    Sets the credential with Shared Access Signature for the Service Bus resource. Refer to Service Bus access control with Shared Access Signatures.
    
    Parameters:
    
    fullyQualifiedNamespace - The fully-qualified namespace for the Service Bus.
    
    credential - AzureSasCredential to be used for authentication.
    
    Returns:
    
    The updated ServiceBusClientBuilder object.
  - proxyOptions
```
public ServiceBusClientBuilder proxyOptions(com.azure.core.amqp.ProxyOptions proxyOptions)
```
    Sets the proxy configuration to use for ServiceBusSenderAsyncClient. When a proxy is configured, AmqpTransportType.AMQP_WEB_SOCKETS must be used for the transport type.
    
    Parameters:
    
    proxyOptions - The proxy configuration to use.
    
    Returns:
    
    The updated ServiceBusClientBuilder object.
  - retryOptions
```
public ServiceBusClientBuilder retryOptions(com.azure.core.amqp.AmqpRetryOptions retryOptions)
```
    Sets the retry options for Service Bus clients. If not specified, the default retry options are used.
    
    Parameters:
    
    retryOptions - The retry options to use.
    
    Returns:
    
    The updated ServiceBusClientBuilder object.
  - transportType
```
public ServiceBusClientBuilder transportType(com.azure.core.amqp.AmqpTransportType transportType)
```
    Sets the transport type by which all the communication with Azure Service Bus occurs. Default value is AmqpTransportType.AMQP.
    
    Parameters:
    
    transportType - The transport type to use.
    
    Returns:
    
    The updated ServiceBusClientBuilder object.
  - sender
```
public ServiceBusClientBuilder.ServiceBusSenderClientBuilder sender()
```
    A new instance of ServiceBusClientBuilder.ServiceBusSenderClientBuilder used to configure Service Bus message senders.
    
    Returns:
    
    A new instance of ServiceBusClientBuilder.ServiceBusSenderClientBuilder.
  - receiver
```
public ServiceBusClientBuilder.ServiceBusReceiverClientBuilder receiver()
```
    A new instance of ServiceBusClientBuilder.ServiceBusReceiverClientBuilder used to configure Service Bus message receivers.
    
    Returns:
    
    A new instance of ServiceBusClientBuilder.ServiceBusReceiverClientBuilder.
  - sessionReceiver
```
public ServiceBusClientBuilder.ServiceBusSessionReceiverClientBuilder sessionReceiver()
```
    A new instance of ServiceBusClientBuilder.ServiceBusSessionReceiverClientBuilder used to configure session aware Service Bus message receivers.
    
    Returns:
    
    A new instance of ServiceBusClientBuilder.ServiceBusSessionReceiverClientBuilder.
  - processor
```
public ServiceBusClientBuilder.ServiceBusProcessorClientBuilder processor()
```
    A new instance of ServiceBusClientBuilder.ServiceBusProcessorClientBuilder used to configure ServiceBusProcessorClient instance.
    
    Returns:
    
    A new instance of ServiceBusClientBuilder.ServiceBusProcessorClientBuilder.
  - sessionProcessor
```
public ServiceBusClientBuilder.ServiceBusSessionProcessorClientBuilder sessionProcessor()
```
    A new instance of ServiceBusClientBuilder.ServiceBusSessionProcessorClientBuilder used to configure a Service Bus processor instance that processes sessions.
    
    Returns:
    
    A new instance of ServiceBusClientBuilder.ServiceBusSessionProcessorClientBuilder.

Visit the Azure for Java Developers site for more Java documentation, including quick starts, tutorials, and code samples.

Class ServiceBusClientBuilder

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ServiceBusClientBuilder

Method Detail

clientOptions

connectionString

enableCrossEntityTransactions

configuration

credential

credential

credential

proxyOptions

retryOptions

transportType

sender

receiver

sessionReceiver

processor

sessionProcessor