Skip to content

Latest commit

 

History

History
483 lines (367 loc) · 20.4 KB

README.md

File metadata and controls

483 lines (367 loc) · 20.4 KB
Raw

Azure Storage Queue client library for Java

Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or HTTPS. A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account.

Source code | API reference documentation | Product documentation | Samples

Getting started

Prerequisites

Adding the package to your product

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-queue</artifactId>
  <version>12.0.0</version>
</dependency>

Default HTTP Client

All client libraries, by default, use Netty HTTP client. Adding the above dependency will automatically configure Storage Queue to use Netty HTTP client.

Alternate HTTP client

If, instead of Netty it is preferable to use OkHTTP, there is a HTTP client available for that too. Exclude the default Netty and include OkHTTP client in your pom.xml.

<!-- Add Storage Queue dependency without Netty HTTP client -->
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-queue</artifactId>
      <version>12.0.0</version>
    <exclusions>
      <exclusion>
        <groupId>com.azure</groupId>
        <artifactId>azure-core-http-netty</artifactId>
      </exclusion>
    </exclusions>
</dependency>
<!-- Add OkHTTP client to use with Storage Queue -->
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-http-okhttp</artifactId>
  <version>1.0.0</version>
</dependency>

Configuring HTTP Clients

When an HTTP client is included on the classpath, as shown above, it is not necessary to specify it in the client library builders, unless you want to customize the HTTP client in some fashion. If this is desired, the httpClient builder method is often available to achieve just this, by allowing users to provide a custom (or customized) com.azure.core.http.HttpClient instances.

For starters, by having the Netty or OkHTTP dependencies on your classpath, as shown above, you can create new instances of these HttpClient types using their builder APIs. For example, here is how you would create a Netty HttpClient instance:

HttpClient client = new NettyAsyncHttpClientBuilder()
    .port(8080)
    .wiretap(true)
    .build();

Create a Storage Account

To create a Storage Account you can use the Azure Portal or Azure CLI.

az group create --name storage-resource-group --location westus

Authenticate the client

In order to interact with the Storage service (Blob, Queue, Message, MessageId, File) you'll need to create an instance of the Service Client class. To make this possible you'll need the Account SAS (shared access signature) string of Storage account. Learn more at SAS Token

Get Credentials

  • SAS Token

a. Use the Azure CLI snippet below to get the SAS token from the Storage account.

az storage queue generate-sas
    --name {queue name}
    --expiry {date/time to expire SAS token}
    --permission {permission to grant}
    --connection-string {connection string of the storage account}
CONNECTION_STRING=<connection-string>
az storage queue generate-sas
    --name javasdksas
    --expiry 2019-06-05
    --permission rpau
    --connection-string $CONNECTION_STRING

b. Alternatively, get the Account SAS Token from the Azure Portal.

Go to your storage account -> Shared access signature -> Click on Generate SAS and connection string (after setup)
  • Shared Key Credential

a. Use account name and account key. Account name is your storage account name.

// Here is where we get the key
Go to your storage account -> Access keys -> Key 1/ Key 2 -> Key

b. Use the connection string

// Here is where we get the key
Go to your storage account -> Access Keys -> Keys 1/ Key 2 -> Connection string

Key concepts

URL format

Queues are addressable using the following URL format: The following URL addresses a queue in the diagram: https://myaccount.queue.core.windows.net/images-to-download

Resource URI Syntax

For the storage account, the base URI for queue operations includes the name of the account only:

https://myaccount.queue.core.windows.net

For a queue, the base URI includes the name of the account and the name of the queue:

https://myaccount.queue.core.windows.net/myqueue

Handling Exceptions

Uses the queueServiceClient generated from Queue Service Client section below.

try {
   queueServiceClient.createQueue("myQueue");
} catch (QueueStorageException e) {
   logger.error("Failed to create a queue with error code: " + e.getErrorCode());
}

Queue Names

Every queue within an account must have a unique name. The queue name must be a valid DNS name, and cannot be changed once created. Queue names must confirm to the following rules:

  1. A queue name must start with a letter or number, and can only contain letters, numbers, and the dash (-) character.
  2. The first and last letters in the queue name must be alphanumeric. The dash (-) character cannot be the first or last character. Consecutive dash characters are not permitted in the queue name.
  3. All letters in a queue name must be lowercase.
  4. A queue name must be from 3 through 63 characters long.

Queue Services

The queue service do operations on the queues in the storage account and manage the queue properties.

Queue Service Client

The client performs the interactions with the Queue service, create or delete a queue, getting and setting Queue properties, list queues in account, and get queue statistics. An asynchronous, QueueServiceAsyncClient, and synchronous, QueueClient, client exists in the SDK allowing for selection of a client based on an application's use case. Once you have the value of the SASToken you can create the queue service client with ${accountName}, ${SASToken}.

String queueURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueURL).sasToken(SASToken).build();

QueueClient newQueueClient = queueServiceClient.createQueue("myqueue");

or

String queueServiceAsyncURL = String.format("https://%s.queue.core.windows.net/", accountName);
QueueServiceAsyncClient queueServiceAsyncClient = new QueueServiceClientBuilder().endpoint(queueServiceAsyncURL)
.sasToken(SASToken).buildAsyncClient();
queueServiceAsyncClient.createQueue("newAsyncQueue").subscribe(
    result -> {
      // do something when new queue created
    },
    error -> {
      // do something if something wrong happened
    },
    () -> {
      // completed, do something
    });

Queue

Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or HTTPS. A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account.

QueueClient

Once you have the value of the SASToken you can create the queue service client with ${accountName}, ${queueName}, ${SASToken}.

String queueURL = String.format("https://%s.queue.core.windows.net/%s", accountName, queueName);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SASToken).buildClient();

// metadata is map of key-value pair
queueClient.createWithResponse(metadata, null, Duration.ofSeconds(30), Context.NONE);

or

String queueAsyncURL = String.format("https://%s.queue.core.windows.net/%s%s", accountName, queueAsyncName, sasToken);
QueueAsyncClient queueAsyncClient = new QueueClientBuilder().endpoint(queueAsyncURL).buildAsyncClient();
queueAsyncClient.createWithResponse(metadata).subscribe(
    result -> {
        // do something when new queue created
    },
    error -> {
        // do something if something wrong happened
    },
    () -> {
        // completed, do something
    });

Examples

The following sections provide several code snippets covering some of the most common Configuration Service tasks, including:

Build a client

We have two ways of building QueueService or Queue Client. Here will take queueServiceClient as an example. Same things apply to queueClient.

First, build client from full URL/endpoint (e.g. with queueName, with SASToken and etc.)

String queueServiceURL = String.format("https://%s.queue.core.windows.net/%s", accountName, sasToken);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL).buildClient();

Or

We can build the queueServiceClient from the builder using ${SASToken} as credential.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL).sasToken(SASToken).buildClient();

Create a queue

Create a queue in the Storage Account using ${SASToken} as credential. Throws StorageException If the queue fails to be created.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL).sasToken(SASToken).buildClient();

QueueClient newQueueClient = queueServiceClient.createQueue("myqueue");

Delete a queue

Delete a queue in the Storage Account using ${SASToken} as credential. Throws StorageException If the queue fails to be deleted.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL).sasToken(SASToken).buildClient();

queueServiceClient.deleteQueue("myqueue");

List queues in account

List all the queues in account using ${SASToken} as credential.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL).sasToken(SASToken).buildClient();
// @param marker: Starting point to list the queues
// @param options: Filter for queue selection
// @param timeout: An optional timeout applied to the operation.
// @param context: Additional context that is passed through the Http pipeline during the service call.
queueServiceClient.listQueues(markers, options, timeout, context).stream().forEach(
    queueItem -> {System.out.printf("Queue %s exists in the account.", queueItem.getName());}
);

Get properties in queue account

Get queue properties in account, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

Use ${SASToken} as credential.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL).sasToken(SASToken).buildClient();

QueueServiceProperties properties = queueServiceClient.getProperties();

Set properties in queue account

Set queue properties in account, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

Use ${SASToken} as credential.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL).sasToken(SASToken).buildClient();

QueueServiceProperties properties = queueServiceClient.getProperties();
properties.setCors(Collections.emptyList());
queueServiceClient.setProperties(properties);

Get queue service statistics

The Get Queue Service Stats operation retrieves statistics related to replication for the Queue service.

Use ${SASToken} as credential. It is only available on the secondary location endpoint when read-access geo-redundant replication is enabled for the storage account.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL).sasToken(SASToken).buildClient();

QueueServiceStatistics queueStats = queueServiceClient.getStatistics();

Enqueue message into a queue

The operation adds a new message to the back of the message queue. A visibility timeout can also be specified to make the message invisible until the visibility timeout expires.

Use ${SASToken} as credential. A message must be in a format that can be included in an XML request with UTF-8 encoding. The encoded message can be up to 64 KB in size for versions 2011-08-18 and newer, or 8 KB in size for previous versions.

String queueSURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SASToken).queueName("myqueue").buildClient();

queueClient.sendMessage("myMessage");

Update a message in a queue

The operation updates a message in the message queue. Use ${SASToken} as credential.

String queueSURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SASToken).queueName("myqueue").buildClient();
// @param messageId Id of the message
// @param popReceipt Unique identifier that must match the message for it to be updated
// @param visibilityTimeout How long the message will be invisible in the queue in seconds
queueClient.updateMessage(messageId ,popReceipt, "new message", visibilityTimeout);

Peek at messages in a queue

The operation retrieves one or more messages from the front of the queue. Use ${SASToken} as credential.

String queueSURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SASToken).queueName("myqueue").buildClient();
// @param key The key with which the specified value should be associated.
// @param value The value to be associated with the specified key.
queueClient.peekMessages(5, Duration.ofSeconds(1), new Context(key, value)).forEach(message-> {System.out.println(message.getMessageText());});

Receive messages from a queue

The operation retrieves one or more messages from the front of the queue. Use ${SASToken} as credential.

String queueSURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SASToken).queueName("myqueue").buildClient();
// Try to receive 10 mesages: Maximum number of messages to get
queueClient.receiveMessages(10).forEach(message-> {System.out.println(message.getMessageText());});

Delete message from a queue

The operation retrieves one or more messages from the front of the queue. Use ${SASToken} as credential.

String queueSURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SASToken).queueName("myqueue").buildClient();

queueClient.deleteMessage(messageId, popReceipt);

Get a queue properties

The operation retrieves user-defined metadata and queue properties on the specified queue. Metadata is associated with the queue as name-values pairs.

Use ${SASToken} as credential.

String queueSURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SASToken).queueName("myqueue").buildClient();

QueueProperties properties = queueClient.getProperties();

Set a queue metadata

The operation sets user-defined metadata on the specified queue. Metadata is associated with the queue as name-value pairs.

Use ${SASToken} as credential.

String queueSURL = String.format("https://%s.queue.core.windows.net", accountName);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SASToken).queueName("myqueue").buildClient();

Map<String, String> metadata =  new HashMap<String, String>() {{
    put("key1", "val1");
    put("key2", "val2");
}};
queueClient.setMetadata(metadata);

Troubleshooting

General

When you interact with queue using this Java client library, errors returned by the service correspond to the same HTTP status codes returned for REST API requests. For example, if you try to retrieve a queue that doesn't exist in your Storage Account, a 404 error is returned, indicating Not Found.

Next steps

Several Storage Queue Java SDK samples are available to you in the SDK's GitHub repository. These samples provide example code for additional scenarios commonly encountered while working with Key Vault:

Next steps Samples

Samples are explained in detail here.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

If you would like to become an active contributor to this project please follow the instructions provided in Microsoft Azure Projects Contribution Guidelines.

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Impressions