Storage Blob Service SDK Migration Guide from 10.x to 12.x

In this section, we list main changes you need to be aware of when converting your Storage Blob SDK library from Version 10 to Version 12.

Prerequisites

Java Development Kit (JDK) with version 8 or above

Update reactive framework from RxJava to Reactor

The biggest payoff here is the switch to Reactor and ReactorNetty. Both Reactor and Reactor-Netty are much more mature than the ReactiveX + custom-ReactiveX-Netty-interface we were using. Both Reactor and ReactorNetty are maintained by Spring and support other large projects, making them safer and more modern, while similar to what was present in v10. For more info, please refer Reactor Project

Performance Increase by using ReactorNetty

Perf increases over purely synchronous HTTP Clients (e.g. OkHttp). In our long running stress tests, we have observed 3x better performance using Reactor-Netty over OkHttp when using our sync apis. The async apis perform even better. Stress tests result. (placeholder)

Rename client:

Class name in V10:

ServiceURL
ContainerURL
BlobURL
BlockBlobURL
AppendBlobURL
PageBlobURL

Sync Class name in V12:

BlobServiceClient
ContainerClient
BlobClient
BlockBlobClient
AppendBlobClient
PageBlobClient

Async Class name in V12:

BlobServiceAsyncClient
ContainerAsyncClient
BlobAsyncClient
BlockBlobAsyncClient
AppendBlobAsyncClient
PageBlobAsyncClient

Provide sis by side sync-over-async APIs

Each type (Container, Blob, etc.) has both a sync and async client. It is easy and intuitive to use whichever one is preferable in a given context without having to bother about clutter from the other.

• Example of using Async API in V12. (Suppose the containerClienthas been initialized. Please refer the Build Client section.)

Mono<Response<BlobProperties>> response = containerClient.getProperties();

• Example of usingSync API in V12

BlobProperties blobProperties = containerClient.getProperties();

Added Maven dependency

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-blob</artifactId>
  <version>12.0.0-preview.2</version>
</dependency>

Credential

There are 3 ways of authenticating the client.

Connection string

In V12, we allow to build connection string through the builder.

BlockBlobClient client = new BlobClientBuilder()
              .connectionstring("${connectionstring}").buildBlockBlobClient();

SAS token

You can build the SAS token through the client builder endpoint. Adds the sasToken from portal at the end of the endpoint. Refer the documentation for more info. e.g.

https://${accountName}.blob.core.windows.net/?${sasToken}

The other way to do that is to use the generateSASToken API

String identifier = "identifier";
FileSASPermission permissions = new FileSASPermission()
            .read(true)
            .create(true)
            .delete(true)
            .write(true);
OffsetDateTime startTime = OffsetDateTime.now().minusDays(1);
OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);
IPRange ipRange = new IPRange()
            .ipMin("0.0.0.0")
            .ipMax("255.255.255.255");
SASProtocol sasProtocol = SASProtocol.HTTPS_HTTP;
String cacheControl = "cache";
String contentDisposition = "disposition";
String contentEncoding = "encoding";
String contentLanguage = "language";
String contentType = "type";
String version = Constants.HeaderConstants.TARGET_STORAGE_VERSION;
String sas = fileClient.generateSAS(identifier, permissions, expiryTime, startTime, version, sasProtocol,
            ipRange, cacheControl, contentDisposition, contentEncoding, contentLanguage, contentType);
SASTokenCredential credential = SASTokenCredential.fromSASTokenString(sas);

Build Client

In V12, you need to use the client builder to build the clients. Constructor pattern is not available. Create client in v10:

final BlockBlobURL blobURL = new BlockBlobURL(
    new URL("https://" + accountName + ".blob.core.windows.net/mycontainer/myimage.jpg"), 
        StorageURL.createPipeline(creds, new PipelineOptions())
);

Build Sync client in v12:

final BlockBlobClient blobClient = new BlobClientBuilder().endpoint("<your-storage-blob-url>")
        .credential("<your-sasToken>")
        .buildBlockBlobClient();

Build Async client in v12:

final BlockBlobAsyncClient blobAsyncClient = new BlobClientBuilder().endpoint("<your-storage-blob-url>")
        .credential("<your-sasToken>")
        .buildBlockBlobAsyncClient();

Sync APIs

For most of async APIs in V10, we will find corresponding sync APIs. E.g. Async API getProperties() in V10:

Single<BlobGetPropertiesResponse> response = blobURL.getProperties();

Corresponding sync API in V12:

BlobProperties blobProperties = containerClient.getProperties();

Async APIs

In V12, we have provided single event Async API (Mono) and Multiple event Async API (PageFlux) E.g. Single event in V10:

E.g. Multiple events in V10:

E.g. Single event in V12:

E.g. Multiple events in V12:

Pagination:

Instead of Single<ListT> in V10, V12 provids two Pagination class PagedIterable<T> over Sync and PageFlux<T> over Async.

BlobInputStream and BlobOutputStream

With the addition of Sync APIs, BlobInputStream and BlobOutputStream fit nicely within this story. Customers who have long depended on these types will find the same interface and will require minimal upgrade. We will also be adding Client-Side Encryption as we bring the library to full parity.