Class QueueServiceClientBuilder
- java.lang.Object
-
- com.azure.storage.queue.QueueServiceClientBuilder
-
public final class QueueServiceClientBuilder extends Object
This class provides a fluent builder API to help aid the configuration and instantiation of thequeueServiceClients
andqueueServiceAsyncClients
, callingbuildClient
constructs an instance of QueueServiceClient and callingbuildAsyncClient
constructs an instance of QueueServiceAsyncClient.The client needs the endpoint of the Azure Storage Queue service, name of the share, and authorization credential.
endpoint
gives the builder the endpoint and may give the builder the a SAS token that authorizes the client.Instantiating a synchronous Queue Service Client with SAS token
QueueServiceClient client = new QueueServiceClientBuilder() .endpoint("https://${accountName}.queue.core.windows.net?${SASToken}") .buildClient();
Instantiating an Asynchronous Queue Service Client with SAS token
QueueServiceAsyncClient client = new QueueServiceClientBuilder() .endpoint("https://{accountName}.queue.core.windows.net?{SASToken}") .buildAsyncClient();
If the
endpoint
doesn't contain the query parameters to construct a SAS token they may be set usingsasToken
together with endpoint.Instantiating a synchronous Queue Service Client with SAS token
QueueServiceAsyncClient client = new QueueServiceClientBuilder() .endpoint("https://{accountName}.queue.core.windows.net") .sasToken("{SASTokenQueryParams}") .buildAsyncClient();
Instantiating an Asynchronous Queue Service Client with SAS token
QueueServiceAsyncClient client = new QueueServiceClientBuilder() .endpoint("https://{accountName}.queue.core.windows.net") .sasToken("{SASTokenQueryParams}") .buildAsyncClient();
Another way to authenticate the client is using a
StorageSharedKeyCredential
. To create a StorageSharedKeyCredential a connection string from the Storage Queue service must be used. Set the StorageSharedKeyCredential withconnectionString
. If the builder has both a SAS token and StorageSharedKeyCredential the StorageSharedKeyCredential will be preferred when authorizing requests sent to the service.Instantiating a synchronous Queue Service Client with connection string.
String connectionString = "DefaultEndpointsProtocol=https;AccountName={name};" + "AccountKey={key};EndpointSuffix={core.windows.net}"; QueueServiceClient client = new QueueServiceClientBuilder() .connectionString(connectionString) .buildClient();
Instantiating an Asynchronous Queue Service Client with connection string.
String connectionString = "DefaultEndpointsProtocol=https;AccountName={name};" + "AccountKey={key};EndpointSuffix={core.windows.net}"; QueueServiceAsyncClient client = new QueueServiceClientBuilder() .connectionString(connectionString) .buildAsyncClient();
-
-
Constructor Summary
Constructors Constructor Description QueueServiceClientBuilder()
Creates a builder instance that is able to configure and constructQueueServiceClients
andQueueServiceAsyncClients
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description QueueServiceClientBuilder
addPolicy(com.azure.core.http.policy.HttpPipelinePolicy pipelinePolicy)
Adds a pipeline policy to apply on each request sent.QueueServiceAsyncClient
buildAsyncClient()
Creates aQueueServiceAsyncClient
based on options set in the builder.QueueServiceClient
buildClient()
Creates aQueueServiceClient
based on options set in the builder.QueueServiceClientBuilder
clientOptions(com.azure.core.util.ClientOptions clientOptions)
Sets the client options for all the requests made through the client.QueueServiceClientBuilder
configuration(com.azure.core.util.Configuration configuration)
Sets the configuration object used to retrieve environment configuration values during building of the client.QueueServiceClientBuilder
connectionString(String connectionString)
Sets the connection string to connect to the service.QueueServiceClientBuilder
credential(com.azure.core.credential.AzureSasCredential credential)
Sets theAzureSasCredential
used to authorize requests sent to the service.QueueServiceClientBuilder
credential(com.azure.core.credential.TokenCredential credential)
Sets theTokenCredential
used to authorize requests sent to the service.QueueServiceClientBuilder
credential(StorageSharedKeyCredential credential)
Sets theStorageSharedKeyCredential
used to authorize requests sent to the service.QueueServiceClientBuilder
endpoint(String endpoint)
Sets the endpoint for the Azure Storage Queue instance that the client will interact with.static com.azure.core.http.policy.HttpLogOptions
getDefaultHttpLogOptions()
Gets the default Storage allowlist log headers and query parameters.QueueServiceClientBuilder
httpClient(com.azure.core.http.HttpClient httpClient)
Sets theHttpClient
to use for sending a receiving requests to and from the service.QueueServiceClientBuilder
httpLogOptions(com.azure.core.http.policy.HttpLogOptions logOptions)
Sets theHttpLogOptions
for service requests.QueueServiceClientBuilder
messageEncoding(QueueMessageEncoding messageEncoding)
Sets the queue message encoding.QueueServiceClientBuilder
pipeline(com.azure.core.http.HttpPipeline httpPipeline)
Sets theHttpPipeline
to use for the service client.QueueServiceClientBuilder
processMessageDecodingError(Consumer<QueueMessageDecodingError> processMessageDecodingErrorHandler)
Sets the handler that performs the tasks needed when a message is received or peaked from the queue but cannot be decoded.QueueServiceClientBuilder
processMessageDecodingErrorAsync(Function<QueueMessageDecodingError,Mono<Void>> processMessageDecodingErrorAsyncHandler)
Sets the asynchronous handler that performs the tasks needed when a message is received or peaked from the queue but cannot be decoded.QueueServiceClientBuilder
retryOptions(RequestRetryOptions retryOptions)
Sets the request retry options for all the requests made through the client.QueueServiceClientBuilder
sasToken(String sasToken)
Sets the SAS token used to authorize requests sent to the service.QueueServiceClientBuilder
serviceVersion(QueueServiceVersion version)
Sets theQueueServiceVersion
that is used when making API requests.
-
-
-
Constructor Detail
-
QueueServiceClientBuilder
public QueueServiceClientBuilder()
Creates a builder instance that is able to configure and constructQueueServiceClients
andQueueServiceAsyncClients
.
-
-
Method Detail
-
buildAsyncClient
public QueueServiceAsyncClient buildAsyncClient()
Creates aQueueServiceAsyncClient
based on options set in the builder. Every time this is called a new instance ofQueueServiceAsyncClient
is created.If
pipeline
is set, then thepipeline
andendpoint
are used to create theclient
. All other builder settings are ignored.- Returns:
- A QueueServiceAsyncClient with the options set from the builder.
- Throws:
NullPointerException
- Ifendpoint
orqueueName
have not been set.IllegalArgumentException
- If neither aStorageSharedKeyCredential
orSAS token
has been set.IllegalStateException
- If multiple credentials have been specified.
-
buildClient
public QueueServiceClient buildClient()
Creates aQueueServiceClient
based on options set in the builder. Every time this is called a new instance ofQueueServiceClient
is created.If
pipeline
is set, then thepipeline
andendpoint
are used to create theclient
. All other builder settings are ignored.- Returns:
- A QueueServiceClient with the options set from the builder.
- Throws:
NullPointerException
- Ifendpoint
orqueueName
have not been set.IllegalArgumentException
- If neither aStorageSharedKeyCredential
orSAS token
has been set.IllegalStateException
- If multiple credentials have been specified.
-
endpoint
public QueueServiceClientBuilder endpoint(String endpoint)
Sets the endpoint for the Azure Storage Queue instance that the client will interact with.Query parameters of the endpoint will be parsed in an attempt to generate a SAS token to authenticate requests sent to the service.
- Parameters:
endpoint
- The URL of the Azure Storage Queue instance to send service requests to and receive responses from.- Returns:
- the updated QueueServiceClientBuilder object
- Throws:
NullPointerException
- Ifendpoint
isnull
.IllegalArgumentException
- Ifendpoint
is a malformed URL.
-
credential
public QueueServiceClientBuilder credential(StorageSharedKeyCredential credential)
Sets theStorageSharedKeyCredential
used to authorize requests sent to the service.- Parameters:
credential
-StorageSharedKeyCredential
.- Returns:
- the updated QueueServiceClientBuilder
- Throws:
NullPointerException
- Ifcredential
isnull
.
-
credential
public QueueServiceClientBuilder credential(com.azure.core.credential.TokenCredential credential)
Sets theTokenCredential
used to authorize requests sent to the service.- Parameters:
credential
-TokenCredential
.- Returns:
- the updated QueueServiceClientBuilder
- Throws:
NullPointerException
- Ifcredential
isnull
.
-
sasToken
public QueueServiceClientBuilder sasToken(String sasToken)
Sets the SAS token used to authorize requests sent to the service.- Parameters:
sasToken
- The SAS token to use for authenticating requests. This string should only be the query parameters (with or without a leading '?') and not a full url.- Returns:
- the updated QueueServiceClientBuilder
- Throws:
NullPointerException
- IfsasToken
isnull
.
-
credential
public QueueServiceClientBuilder credential(com.azure.core.credential.AzureSasCredential credential)
Sets theAzureSasCredential
used to authorize requests sent to the service.- Parameters:
credential
-AzureSasCredential
used to authorize requests sent to the service.- Returns:
- the updated QueueServiceClientBuilder
- Throws:
NullPointerException
- Ifcredential
isnull
.
-
connectionString
public QueueServiceClientBuilder connectionString(String connectionString)
Sets the connection string to connect to the service.- Parameters:
connectionString
- Connection string of the storage account.- Returns:
- the updated QueueServiceClientBuilder
- Throws:
IllegalArgumentException
- IfconnectionString
is invalid.
-
httpClient
public QueueServiceClientBuilder httpClient(com.azure.core.http.HttpClient httpClient)
Sets theHttpClient
to use for sending a receiving requests to and from the service.- Parameters:
httpClient
- HttpClient to use for requests.- Returns:
- the updated QueueServiceClientBuilder object
-
addPolicy
public QueueServiceClientBuilder addPolicy(com.azure.core.http.policy.HttpPipelinePolicy pipelinePolicy)
Adds a pipeline policy to apply on each request sent. The policy will be added after the retry policy. If the method is called multiple times, all policies will be added and their order preserved.- Parameters:
pipelinePolicy
- a pipeline policy- Returns:
- the updated QueueServiceClientBuilder object
- Throws:
NullPointerException
- IfpipelinePolicy
isnull
.
-
httpLogOptions
public QueueServiceClientBuilder httpLogOptions(com.azure.core.http.policy.HttpLogOptions logOptions)
Sets theHttpLogOptions
for service requests.- Parameters:
logOptions
- The logging configuration to use when sending and receiving HTTP requests/responses.- Returns:
- the updated QueueServiceClientBuilder object
- Throws:
NullPointerException
- IflogOptions
isnull
.
-
getDefaultHttpLogOptions
public static com.azure.core.http.policy.HttpLogOptions getDefaultHttpLogOptions()
Gets the default Storage allowlist log headers and query parameters.- Returns:
- the default http log options.
-
configuration
public QueueServiceClientBuilder configuration(com.azure.core.util.Configuration configuration)
Sets the configuration object used to retrieve environment configuration values during building of the client.- Parameters:
configuration
- Configuration store used to retrieve environment configurations.- Returns:
- the updated QueueServiceClientBuilder object
-
retryOptions
public QueueServiceClientBuilder retryOptions(RequestRetryOptions retryOptions)
Sets the request retry options for all the requests made through the client.- Parameters:
retryOptions
-RequestRetryOptions
.- Returns:
- the updated QueueServiceClientBuilder object
- Throws:
NullPointerException
- IfretryOptions
isnull
.
-
pipeline
public QueueServiceClientBuilder pipeline(com.azure.core.http.HttpPipeline httpPipeline)
Sets theHttpPipeline
to use for the service client. Ifpipeline
is set, all other settings are ignored, aside fromendpoint
.- Parameters:
httpPipeline
- HttpPipeline to use for sending service requests and receiving responses.- Returns:
- the updated QueueServiceClientBuilder object
-
clientOptions
public QueueServiceClientBuilder clientOptions(com.azure.core.util.ClientOptions clientOptions)
Sets the client options for all the requests made through the client.- Parameters:
clientOptions
-ClientOptions
.- Returns:
- the updated QueueServiceClientBuilder object
- Throws:
NullPointerException
- IfclientOptions
isnull
.
-
messageEncoding
public QueueServiceClientBuilder messageEncoding(QueueMessageEncoding messageEncoding)
Sets the queue message encoding.- Parameters:
messageEncoding
-QueueMessageEncoding
.- Returns:
- the updated QueueServiceClientBuilder object
- Throws:
NullPointerException
- IfmessageEncoding
isnull
.
-
processMessageDecodingErrorAsync
public QueueServiceClientBuilder processMessageDecodingErrorAsync(Function<QueueMessageDecodingError,Mono<Void>> processMessageDecodingErrorAsyncHandler)
Sets the asynchronous handler that performs the tasks needed when a message is received or peaked from the queue but cannot be decoded.Such message can be received or peaked when queue is expecting certain
QueueMessageEncoding
but there's another producer that is not encoding messages in expected way. I.e. the queue contains messages with different encoding.QueueMessageDecodingError
containsQueueAsyncClient
for the queue that has received the message as well asQueueMessageDecodingError.getQueueMessageItem()
orQueueMessageDecodingError.getPeekedMessageItem()
with raw body, i.e. no decoding will be attempted so that body can be inspected as has been received from the queue.The handler won't attempt to remove the message from the queue. Therefore such handling should be included into handler itself.
The handler will be shared by all queue clients that are created from
QueueServiceClient
orQueueServiceAsyncClient
built by this builder.Code Samples
String connectionString = "DefaultEndpointsProtocol=https;AccountName={name};" + "AccountKey={key};EndpointSuffix={core.windows.net}"; Function<QueueMessageDecodingError, Mono<Void>> processMessageDecodingErrorHandler = (queueMessageDecodingFailure) -> { QueueMessageItem queueMessageItem = queueMessageDecodingFailure.getQueueMessageItem(); PeekedMessageItem peekedMessageItem = queueMessageDecodingFailure.getPeekedMessageItem(); if (queueMessageItem != null) { System.out.printf("Received badly encoded message, messageId=%s, messageBody=%s", queueMessageItem.getMessageId(), queueMessageItem.getBody().toString()); return queueMessageDecodingFailure .getQueueAsyncClient() .deleteMessage(queueMessageItem.getMessageId(), queueMessageItem.getPopReceipt()); } else if (peekedMessageItem != null) { System.out.printf("Peeked badly encoded message, messageId=%s, messageBody=%s", peekedMessageItem.getMessageId(), peekedMessageItem.getBody().toString()); return Mono.empty(); } else { return Mono.empty(); } }; QueueServiceClient client = new QueueServiceClientBuilder() .connectionString(connectionString) .processMessageDecodingErrorAsync(processMessageDecodingErrorHandler) .buildClient();
- Parameters:
processMessageDecodingErrorAsyncHandler
- the handler.- Returns:
- the updated QueueServiceClientBuilder object
-
processMessageDecodingError
public QueueServiceClientBuilder processMessageDecodingError(Consumer<QueueMessageDecodingError> processMessageDecodingErrorHandler)
Sets the handler that performs the tasks needed when a message is received or peaked from the queue but cannot be decoded.Such message can be received or peaked when queue is expecting certain
QueueMessageEncoding
but there's another producer that is not encoding messages in expected way. I.e. the queue contains messages with different encoding.QueueMessageDecodingError
containsQueueAsyncClient
for the queue that has received the message as well asQueueMessageDecodingError.getQueueMessageItem()
orQueueMessageDecodingError.getPeekedMessageItem()
with raw body, i.e. no decoding will be attempted so that body can be inspected as has been received from the queue.The handler won't attempt to remove the message from the queue. Therefore such handling should be included into handler itself.
The handler will be shared by all queue clients that are created from
QueueServiceClient
orQueueServiceAsyncClient
built by this builder.Code Samples
String connectionString = "DefaultEndpointsProtocol=https;AccountName={name};" + "AccountKey={key};EndpointSuffix={core.windows.net}"; Consumer<QueueMessageDecodingError> processMessageDecodingErrorHandler = (queueMessageDecodingFailure) -> { QueueMessageItem queueMessageItem = queueMessageDecodingFailure.getQueueMessageItem(); PeekedMessageItem peekedMessageItem = queueMessageDecodingFailure.getPeekedMessageItem(); if (queueMessageItem != null) { System.out.printf("Received badly encoded message, messageId=%s, messageBody=%s", queueMessageItem.getMessageId(), queueMessageItem.getBody().toString()); queueMessageDecodingFailure .getQueueClient() .deleteMessage(queueMessageItem.getMessageId(), queueMessageItem.getPopReceipt()); } else if (peekedMessageItem != null) { System.out.printf("Peeked badly encoded message, messageId=%s, messageBody=%s", peekedMessageItem.getMessageId(), peekedMessageItem.getBody().toString()); } }; QueueServiceClient client = new QueueServiceClientBuilder() .connectionString(connectionString) .processMessageDecodingError(processMessageDecodingErrorHandler) .buildClient();
- Parameters:
processMessageDecodingErrorHandler
- the handler.- Returns:
- the updated QueueServiceClientBuilder object
-
serviceVersion
public QueueServiceClientBuilder serviceVersion(QueueServiceVersion version)
Sets theQueueServiceVersion
that is used when making API requests.If a service version is not provided, the service version that will be used will be the latest known service version based on the version of the client library being used. If no service version is specified, updating to a newer version of the client library will have the result of potentially moving to a newer service version.
Targeting a specific service version may also mean that the service will return an error for newer APIs.
- Parameters:
version
-QueueServiceVersion
of the service to be used when making requests.- Returns:
- the updated QueueServiceClientBuilder object
-
-