or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

blob-client.mdcontainer-client.mdindex.mdmodels.mdoptions.mdsecurity.mdservice-client.mdspecialized-clients.mdstreaming.md
tile.json

tessl/maven-com-azure--azure-storage-blob

Microsoft Azure client library for Blob Storage - Azure Blob Storage is Microsoft's object storage solution for the cloud, optimized for storing massive amounts of unstructured data such as text or binary data.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.azure/azure-storage-blob@12.30.x

To install, run

npx @tessl/cli install tessl/maven-com-azure--azure-storage-blob@12.30.0

index.mddocs/

Azure Storage Blob Java SDK

The Azure Storage Blob Java SDK provides comprehensive functionality for working with Azure Blob Storage, supporting all blob types and advanced features like encryption, access control, and high-performance data transfer.

Package Information

  • Package Name: azure-storage-blob
  • Package Type: Maven
  • Language: Java
  • Installation:
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>12.30.0</version>
</dependency>

Core Imports

// Main client classes
import com.azure.storage.blob.BlobServiceClient;
import com.azure.storage.blob.BlobServiceClientBuilder;
import com.azure.storage.blob.BlobContainerClient;
import com.azure.storage.blob.BlobClient;

// Async clients
import com.azure.storage.blob.BlobServiceAsyncClient;
import com.azure.storage.blob.BlobContainerAsyncClient;
import com.azure.storage.blob.BlobAsyncClient;

// Specialized blob clients
import com.azure.storage.blob.specialized.BlockBlobClient;
import com.azure.storage.blob.specialized.AppendBlobClient;
import com.azure.storage.blob.specialized.PageBlobClient;

// Model classes
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.options.*;

// Authentication
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.storage.common.StorageSharedKeyCredential;

Basic Usage

Creating a Service Client

// Using connection string (simplest)
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
    .connectionString("DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=...")
    .buildClient();

// Using Azure Identity (recommended for production)
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
    .endpoint("https://myaccount.blob.core.windows.net")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

// Using account key
StorageSharedKeyCredential credential = new StorageSharedKeyCredential("myaccount", "accountKey");
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
    .endpoint("https://myaccount.blob.core.windows.net")
    .credential(credential)
    .buildClient();

Container and Blob Operations

// Get container client
BlobContainerClient containerClient = serviceClient.getBlobContainerClient("mycontainer");

// Create container if it doesn't exist
containerClient.createIfNotExists();

// Get blob client
BlobClient blobClient = containerClient.getBlobClient("myblob.txt");

// Upload data
String data = "Hello, Azure Blob Storage!";
blobClient.upload(BinaryData.fromString(data), true);

// Download data
BinaryData downloadedData = blobClient.downloadContent();
String content = downloadedData.toString();

Architecture

Client Hierarchy

The Azure Storage Blob SDK follows a three-tier client hierarchy:

  1. BlobServiceClient - Top-level client for service operations and container management
  2. BlobContainerClient - Container-specific operations and blob management
  3. BlobClient - Individual blob operations and data transfer

Each tier provides both synchronous and asynchronous variants:

  • Synchronous: BlobServiceClient, BlobContainerClient, BlobClient
  • Asynchronous: BlobServiceAsyncClient, BlobContainerAsyncClient, BlobAsyncClient

Specialized Blob Types

Azure Blob Storage supports three blob types with specialized clients:

  • Block Blobs (BlockBlobClient) - General-purpose blobs, optimized for streaming and upload scenarios
  • Append Blobs (AppendBlobClient) - Optimized for append operations, ideal for logging
  • Page Blobs (PageBlobClient) - Random read/write access, used for VHD files and databases

Capabilities

Service Management

Manage Azure Blob Storage service-level operations, container lifecycle, and account properties.

// List all containers
PagedIterable<BlobContainerItem> containers = serviceClient.listBlobContainers();

// Get account information
StorageAccountInfo accountInfo = serviceClient.getAccountInfo();

// Configure service properties
BlobServiceProperties properties = serviceClient.getProperties();
properties.setDefaultServiceVersion("2023-11-03");
serviceClient.setProperties(properties);

Learn more about service management →

Container Operations

Create, configure, and manage blob containers with access policies and metadata.

// Create container with metadata
Map<String, String> metadata = Map.of("environment", "production");
BlobContainerCreateOptions options = new BlobContainerCreateOptions()
    .setMetadata(metadata)
    .setPublicAccessType(PublicAccessType.BLOB);
containerClient.createWithResponse(options, Duration.ofSeconds(30), Context.NONE);

// List blobs with filtering
ListBlobsOptions listOptions = new ListBlobsOptions()
    .setPrefix("logs/")
    .setDetails(new BlobListDetails().setRetrieveMetadata(true));
PagedIterable<BlobItem> blobs = containerClient.listBlobs(listOptions, Duration.ofSeconds(30));

Learn more about container operations →

Blob Upload & Download

Efficient data transfer with support for large files, parallel uploads, and streaming.

// Upload from file with progress tracking
ParallelTransferOptions transferOptions = new ParallelTransferOptions()
    .setBlockSizeLong(4 * 1024 * 1024L) // 4MB blocks
    .setMaxConcurrency(4)
    .setProgressListener(bytesTransferred -> 
        System.out.println("Transferred: " + bytesTransferred + " bytes"));

BlobUploadFromFileOptions uploadOptions = new BlobUploadFromFileOptions("localfile.dat")
    .setParallelTransferOptions(transferOptions)
    .setHeaders(new BlobHttpHeaders().setContentType("application/octet-stream"))
    .setTier(AccessTier.HOT);

blobClient.uploadFromFileWithResponse(uploadOptions, Duration.ofMinutes(5), Context.NONE);

// Download to file with retry options
DownloadRetryOptions retryOptions = new DownloadRetryOptions()
    .setMaxRetryRequests(3);

BlobDownloadToFileOptions downloadOptions = new BlobDownloadToFileOptions("downloadedfile.dat")
    .setDownloadRetryOptions(retryOptions)
    .setParallelTransferOptions(transferOptions);

blobClient.downloadToFileWithResponse(downloadOptions, Duration.ofMinutes(5), Context.NONE);

Learn more about blob operations →

Specialized Blob Types

Work with specific blob types optimized for different use cases.

// Block blob operations
BlockBlobClient blockBlobClient = blobClient.getBlockBlobClient();
List<String> blockIds = Arrays.asList("block1", "block2", "block3");
blockBlobClient.commitBlockList(blockIds);

// Append blob operations  
AppendBlobClient appendBlobClient = blobClient.getAppendBlobClient();
appendBlobClient.create();
appendBlobClient.appendBlock(BinaryData.fromString("Log entry 1\n"));

// Page blob operations
PageBlobClient pageBlobClient = blobClient.getPageBlobClient();
pageBlobClient.create(512 * 1024); // 512KB
PageRange range = new PageRange().setStart(0).setEnd(511);
pageBlobClient.uploadPages(range, BinaryData.fromBytes(new byte[512]));

Learn more about specialized clients →

Security & Authentication

Comprehensive security features including SAS tokens, encryption, and access control.

// Generate SAS token for blob access
OffsetDateTime expiryTime = OffsetDateTime.now().plusHours(1);
BlobSasPermission permission = new BlobSasPermission().setReadPermission(true);

BlobServiceSasSignatureValues sasValues = new BlobServiceSasSignatureValues(expiryTime, permission)
    .setStartTime(OffsetDateTime.now())
    .setProtocol(SasProtocol.HTTPS_ONLY);

String sasToken = blobClient.generateSas(sasValues);

// Customer-provided encryption
CustomerProvidedKey cpk = new CustomerProvidedKey("encryptionKey")
    .setEncryptionAlgorithm(EncryptionAlgorithmType.AES256);

BlobClientBuilder builder = new BlobClientBuilder()
    .endpoint("https://account.blob.core.windows.net")
    .containerName("container")
    .blobName("encrypted-blob")
    .customerProvidedKey(cpk);

Learn more about security features →

Configuration Options

Fine-tune client behavior with comprehensive configuration options.

import com.azure.core.http.HttpClient;
import com.azure.core.http.netty.NettyAsyncHttpClientBuilder;
import com.azure.storage.common.policy.RequestRetryOptions;
import com.azure.storage.common.policy.RetryPolicyType;

// Retry policy configuration
RequestRetryOptions retryOptions = new RequestRetryOptions(
    RetryPolicyType.EXPONENTIAL, 
    3, // maxTries
    Duration.ofSeconds(30), // tryTimeout
    Duration.ofSeconds(1), // retryDelay
    Duration.ofSeconds(120), // maxRetryDelay
    null // secondaryHost
);

// HTTP client configuration
HttpClient httpClient = new NettyAsyncHttpClientBuilder()
    .connectionTimeout(Duration.ofSeconds(60))
    .responseTimeout(Duration.ofSeconds(120))
    .build();

// Build client with custom configuration
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
    .endpoint("https://account.blob.core.windows.net")
    .credential(new DefaultAzureCredentialBuilder().build())
    .retryOptions(retryOptions)
    .httpClient(httpClient)
    .buildClient();

Learn more about configuration options →

Streaming & Advanced I/O

Efficient streaming operations for large data sets and real-time scenarios.

// Streaming upload
Flux<ByteBuffer> dataFlux = Flux.just(ByteBuffer.wrap("data".getBytes()));
BlobParallelUploadOptions uploadOptions = new BlobParallelUploadOptions(dataFlux)
    .setParallelTransferOptions(new ParallelTransferOptions()
        .setBlockSizeLong(1024 * 1024L)
        .setMaxConcurrency(2));

BlobAsyncClient asyncClient = blobClient.getAsyncClient();
asyncClient.uploadWithResponse(uploadOptions).block();

// Streaming download
Flux<ByteBuffer> downloadFlux = asyncClient.downloadStream();
downloadFlux.subscribe(buffer -> {
    // Process each buffer as it arrives
    byte[] bytes = new byte[buffer.remaining()];
    buffer.get(bytes);
    System.out.println("Received " + bytes.length + " bytes");
});

Learn more about streaming operations →

Model Classes & Enums

The SDK provides rich model classes for working with blob properties, metadata, and service configuration.

Core Models

// Blob properties
BlobProperties properties = blobClient.getProperties();
System.out.println("Size: " + properties.getBlobSize());
System.out.println("Content Type: " + properties.getContentType());
System.out.println("Last Modified: " + properties.getLastModified());

// Container properties  
BlobContainerProperties containerProps = containerClient.getProperties();
System.out.println("Public Access: " + containerProps.getPublicAccess());

// Access tiers for cost optimization
blobClient.setAccessTier(AccessTier.COOL); // Hot, Cool, Cold, Archive

Learn more about models and enums →

Error Handling

import com.azure.storage.blob.models.BlobStorageException;

try {
    blobClient.upload(BinaryData.fromString("data"), true);
} catch (BlobStorageException ex) {
    System.err.println("Storage error: " + ex.getErrorCode());
    System.err.println("Status code: " + ex.getStatusCode());
    System.err.println("Message: " + ex.getMessage());
} catch (Exception ex) {
    System.err.println("General error: " + ex.getMessage());
}

Related Documentation