Skip to content
This repository has been archived by the owner on Jul 19, 2024. It is now read-only.

Azure Storage Java V10 Overview

Jump to bottom
Rick Ley edited this page Feb 11, 2019 · 3 revisions

Introduction

Hello and welcome to V10 of the Azure Storage Java SDK! We are excited to have you use our new product! We understand that it is inconvenient to rewrite code related to Azure Storage, but we are here to help you with any difficulty you encounter, and we believe it will be well worth the effort in the way of performance, debuggability, and clarity of code. Included in this page is a detailed overview of the new design to get you started, but first, some things to consider that were left behind in the old version and a couple key ideas from the new design:

  • Connection strings are no longer used. Instead, a ServiceURL endpoint, account name, and credentials (Key, SAS Token, or OAuth Token) are required.
  • No more Blob, File, and Queue objects whose properties got updated whenever a service call was made, which was not thread safe. Methods now return response object that include HTTP headers and the body as appropriate.
  • No more OperationContext. Instead, build an HttpPipeline to mutate HTTP request and responses before the request is sent out and after the response is received.
  • REST API wrappers are included as methods in ServiceURL, BlobURL, and ContainerURL classes. We guarantee a contract that methods in these classes are mapped 1:1 to the REST APIs. E.g. BlockBlobURL.Upload() will result in a single Put Blob operation.
  • High level APIs such as uploading from a file concurrently have moved into the TransferManager class. These methods may trigger multiple REST API requests and include our own assumptions and optimizations. They are built for your convenience but may not suit every need. Feel free to request additional features, contribute code, or use our code as an example for your own extensions as you see fit!

V10 Details

URL Types & Http Pipeline

The most common types you'll work with are the XxxURL types. The methods of these types make requests against the Azure Storage Service.

  • ServiceURL's methods perform operations on a storage account.
    • ContainerURL's methods perform operations on an account's container.
      • BlockBlobURL's methods perform operations on a container's block blob.
      • AppendBlobURL's methods perform operations on a container's append blob.
      • PageBlobURL's methods perform operations on a container's page blob.
      • BlobURL's methods perform operations on a container's blob regardless of the blob's type.

Internally, each XxxURL object contains a URL and a request pipeline (HttpPipeline). The URL indicates the endpoint where each HTTP request is sent and the pipeline indicates how the outgoing HTTP request and incoming HTTP response is processed. The pipeline specifies things like retry policies, logging, deserializaiton of HTTP response payloads, and more. Pipelines are threadsafe and may be shared by multiple XxxURL objects. When you create a ServiceURL, you pass an initial pipeline. When you call ServiceURL's newContainerURL method, the new ContainerURL object has its own URL but it shares the same pipeline as the parent ServiceURL object. To work with a blob, call one of ContainerURL's 4 newXxxBlobURL methods depending on how you want to treat the blob. To treat the blob as a block blob, append blob, or page blob, call newBlockBlobURL, newAppendBlobURL, or newPageBlobURL respectively. These three types are all identical except for the methods they expose; each type exposes the methods relevant to the type of blob represented. If you're not sure how you want to treat a blob, you can call newBlobURL; this returns an object whose methods are relevant to any kind of blob. When you call ContainerURL's newXxxBlobURL, the new XxxBlobURL object has its own URL but it shares the same pipeline as the parent ContainerURL object. If you'd like to use a different pipeline with a ServiceURL, ContainerURL, or XxxBlobURL object, then call the XxxURL object's withPipeline method passing in the desired pipeline. The withPipeline methods create a new XxxURL object with the same URL as the original but with the specified pipeline. Note that XxxURL objects use little memory, are threadsafe, and many objects share the same pipeline. This means that XxxURL objects share a lot of system resources making them very efficient. All of XxxURL's methods that make HTTP requests return rich error handling information so you can discern network failures, transient failures, timeout failures, service failures, etc.

URL and Shared Access Signature Manipulation

The library includes the URLParser and BlobURLParts types for deconstructing and reconstructing URLs respectively. And there are types for generating and parsing Shared Access Signature (SAS)

  • Use the AccountSASSignatureValues type to create a SAS for a storage account
  • Use the ServiceSASSignatureValues type to create a SAS for a container or blob.
  • Use the SASQueryParameters type to turn signature values in to query parameters or to parse query parameters. To generate a SAS, you must use the SharedKeyCredential type.

Credentials

When creating a request pipeline, you must specify one of this package's credential types.

  • Create a new AnonymousCredentials object for requests that contain a Shared Access Signature (SAS) or for requests to public resources.
  • Create a new SharedKeyCredentials object(with an account name & key) to access any and all account resources. You must also use this to generate Shared Access Signatures.
  • Create a new TokenCredentials object to use OAuth authentication. Note that it is the user's responsibility to periodically update the token.

HTTP Request Policy Factories

This package defines several request policy factories for use with the HttpPipeline. Most applications will not use these factories directly; instead, the StorageURL.createPipeline() function creates the these factories, initializes them (via the PipelineOptions type) and returns a pipeline object for use by the XxxURL objects. However, for advanced scenarios, developers can access these policy factories directly and even create their own and then construct their own pipeline in order to affect HTTP requests and responses performed by the XxxURL objects. For example, developers can introduce their own logging, random failures, request recording & playback for fast testing, HTTP request pacing, alternate retry mechanisms, metering, metrics, etc. The possibilities are endless! Below are the request pipeline policy factory functions that are provided with this package:

  • RequestRetryFactory Enables rich retry semantics for failed HTTP requests
  • LoggingFactory Enables rich logging support for HTTP requests/responses & failures
  • TelemetryFactory Enables simple modification of the HTTP request's User-Agent header so each request reports the SDK version & language/runtime making the requests
  • RequestIDFactory Adds a x-ms-client-request-id header with a unique UUID value to an HTTP request to help with diagnosing failures Also, note that all the new XxxCredential returns a request policy factory object which gets injected into the pipeline.
Clone this wiki locally