0
# Azure Storage Blob Java SDK
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: azure-storage-blob
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**:
10

11
```xml
12
<dependency>
13
    <groupId>com.azure</groupId>
14
    <artifactId>azure-storage-blob</artifactId>
15
    <version>12.30.0</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
// Main client classes
23
import com.azure.storage.blob.BlobServiceClient;
24
import com.azure.storage.blob.BlobServiceClientBuilder;
25
import com.azure.storage.blob.BlobContainerClient;
26
import com.azure.storage.blob.BlobClient;
27

28
// Async clients
29
import com.azure.storage.blob.BlobServiceAsyncClient;
30
import com.azure.storage.blob.BlobContainerAsyncClient;
31
import com.azure.storage.blob.BlobAsyncClient;
32

33
// Specialized blob clients
34
import com.azure.storage.blob.specialized.BlockBlobClient;
35
import com.azure.storage.blob.specialized.AppendBlobClient;
36
import com.azure.storage.blob.specialized.PageBlobClient;
37

38
// Model classes
39
import com.azure.storage.blob.models.*;
40
import com.azure.storage.blob.options.*;
41

42
// Authentication
43
import com.azure.identity.DefaultAzureCredentialBuilder;
44
import com.azure.storage.common.StorageSharedKeyCredential;
45
```
46

47
## Basic Usage
48

49
### Creating a Service Client
50

51
```java
52
// Using connection string (simplest)
53
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
54
    .connectionString("DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=...")
55
    .buildClient();
56

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

63
// Using account key
64
StorageSharedKeyCredential credential = new StorageSharedKeyCredential("myaccount", "accountKey");
65
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
66
    .endpoint("https://myaccount.blob.core.windows.net")
67
    .credential(credential)
68
    .buildClient();
69
```
70

71
### Container and Blob Operations
72

73
```java
74
// Get container client
75
BlobContainerClient containerClient = serviceClient.getBlobContainerClient("mycontainer");
76

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

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

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

87
// Download data
88
BinaryData downloadedData = blobClient.downloadContent();
89
String content = downloadedData.toString();
90
```
91

92
## Architecture
93

94
### Client Hierarchy
95

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

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

102
Each tier provides both synchronous and asynchronous variants:
103
- Synchronous: `BlobServiceClient`, `BlobContainerClient`, `BlobClient`
104
- Asynchronous: `BlobServiceAsyncClient`, `BlobContainerAsyncClient`, `BlobAsyncClient`
105

106
### Specialized Blob Types
107

108
Azure Blob Storage supports three blob types with specialized clients:
109

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

114
## Capabilities
115

116
### Service Management
117

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

120
```java
121
// List all containers
122
PagedIterable<BlobContainerItem> containers = serviceClient.listBlobContainers();
123

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

127
// Configure service properties
128
BlobServiceProperties properties = serviceClient.getProperties();
129
properties.setDefaultServiceVersion("2023-11-03");
130
serviceClient.setProperties(properties);
131
```
132

133
[Learn more about service management →](service-client.md)
134

135
### Container Operations
136

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

139
```java
140
// Create container with metadata
141
Map<String, String> metadata = Map.of("environment", "production");
142
BlobContainerCreateOptions options = new BlobContainerCreateOptions()
143
    .setMetadata(metadata)
144
    .setPublicAccessType(PublicAccessType.BLOB);
145
containerClient.createWithResponse(options, Duration.ofSeconds(30), Context.NONE);
146

147
// List blobs with filtering
148
ListBlobsOptions listOptions = new ListBlobsOptions()
149
    .setPrefix("logs/")
150
    .setDetails(new BlobListDetails().setRetrieveMetadata(true));
151
PagedIterable<BlobItem> blobs = containerClient.listBlobs(listOptions, Duration.ofSeconds(30));
152
```
153

154
[Learn more about container operations →](container-client.md)
155

156
### Blob Upload & Download
157

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

160
```java
161
// Upload from file with progress tracking
162
ParallelTransferOptions transferOptions = new ParallelTransferOptions()
163
    .setBlockSizeLong(4 * 1024 * 1024L) // 4MB blocks
164
    .setMaxConcurrency(4)
165
    .setProgressListener(bytesTransferred -> 
166
        System.out.println("Transferred: " + bytesTransferred + " bytes"));
167

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

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

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

179
BlobDownloadToFileOptions downloadOptions = new BlobDownloadToFileOptions("downloadedfile.dat")
180
    .setDownloadRetryOptions(retryOptions)
181
    .setParallelTransferOptions(transferOptions);
182

183
blobClient.downloadToFileWithResponse(downloadOptions, Duration.ofMinutes(5), Context.NONE);
184
```
185

186
[Learn more about blob operations →](blob-client.md)
187

188
### Specialized Blob Types
189

190
Work with specific blob types optimized for different use cases.
191

192
```java
193
// Block blob operations
194
BlockBlobClient blockBlobClient = blobClient.getBlockBlobClient();
195
List<String> blockIds = Arrays.asList("block1", "block2", "block3");
196
blockBlobClient.commitBlockList(blockIds);
197

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

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

210
[Learn more about specialized clients →](specialized-clients.md)
211

212
### Security & Authentication
213

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

216
```java
217
// Generate SAS token for blob access
218
OffsetDateTime expiryTime = OffsetDateTime.now().plusHours(1);
219
BlobSasPermission permission = new BlobSasPermission().setReadPermission(true);
220

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

225
String sasToken = blobClient.generateSas(sasValues);
226

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

231
BlobClientBuilder builder = new BlobClientBuilder()
232
    .endpoint("https://account.blob.core.windows.net")
233
    .containerName("container")
234
    .blobName("encrypted-blob")
235
    .customerProvidedKey(cpk);
236
```
237

238
[Learn more about security features →](security.md)
239

240
### Configuration Options
241

242
Fine-tune client behavior with comprehensive configuration options.
243

244
```java
245
import com.azure.core.http.HttpClient;
246
import com.azure.core.http.netty.NettyAsyncHttpClientBuilder;
247
import com.azure.storage.common.policy.RequestRetryOptions;
248
import com.azure.storage.common.policy.RetryPolicyType;
249

250
// Retry policy configuration
251
RequestRetryOptions retryOptions = new RequestRetryOptions(
252
    RetryPolicyType.EXPONENTIAL, 
253
    3, // maxTries
254
    Duration.ofSeconds(30), // tryTimeout
255
    Duration.ofSeconds(1), // retryDelay
256
    Duration.ofSeconds(120), // maxRetryDelay
257
    null // secondaryHost
258
);
259

260
// HTTP client configuration
261
HttpClient httpClient = new NettyAsyncHttpClientBuilder()
262
    .connectionTimeout(Duration.ofSeconds(60))
263
    .responseTimeout(Duration.ofSeconds(120))
264
    .build();
265

266
// Build client with custom configuration
267
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
268
    .endpoint("https://account.blob.core.windows.net")
269
    .credential(new DefaultAzureCredentialBuilder().build())
270
    .retryOptions(retryOptions)
271
    .httpClient(httpClient)
272
    .buildClient();
273
```
274

275
[Learn more about configuration options →](options.md)
276

277
### Streaming & Advanced I/O
278

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

281
```java
282
// Streaming upload
283
Flux<ByteBuffer> dataFlux = Flux.just(ByteBuffer.wrap("data".getBytes()));
284
BlobParallelUploadOptions uploadOptions = new BlobParallelUploadOptions(dataFlux)
285
    .setParallelTransferOptions(new ParallelTransferOptions()
286
        .setBlockSizeLong(1024 * 1024L)
287
        .setMaxConcurrency(2));
288

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

292
// Streaming download
293
Flux<ByteBuffer> downloadFlux = asyncClient.downloadStream();
294
downloadFlux.subscribe(buffer -> {
295
    // Process each buffer as it arrives
296
    byte[] bytes = new byte[buffer.remaining()];
297
    buffer.get(bytes);
298
    System.out.println("Received " + bytes.length + " bytes");
299
});
300
```
301

302
[Learn more about streaming operations →](streaming.md)
303

304
## Model Classes & Enums
305

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

308
### Core Models
309

310
```java
311
// Blob properties
312
BlobProperties properties = blobClient.getProperties();
313
System.out.println("Size: " + properties.getBlobSize());
314
System.out.println("Content Type: " + properties.getContentType());
315
System.out.println("Last Modified: " + properties.getLastModified());
316

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

321
// Access tiers for cost optimization
322
blobClient.setAccessTier(AccessTier.COOL); // Hot, Cool, Cold, Archive
323
```
324

325
[Learn more about models and enums →](models.md)
326

327
## Error Handling
328

329
```java
330
import com.azure.storage.blob.models.BlobStorageException;
331

332
try {
333
    blobClient.upload(BinaryData.fromString("data"), true);
334
} catch (BlobStorageException ex) {
335
    System.err.println("Storage error: " + ex.getErrorCode());
336
    System.err.println("Status code: " + ex.getStatusCode());
337
    System.err.println("Message: " + ex.getMessage());
338
} catch (Exception ex) {
339
    System.err.println("General error: " + ex.getMessage());
340
}
341
```
342

343
## Related Documentation
344

345
- [Service Client Operations →](service-client.md)
346
- [Container Management →](container-client.md)  
347
- [Blob Operations →](blob-client.md)
348
- [Specialized Blob Types →](specialized-clients.md)
349
- [Model Classes & Enums →](models.md)
350
- [Configuration Options →](options.md)
351
- [Security & Authentication →](security.md)
352
- [Streaming & Advanced I/O →](streaming.md)