Azure Storage Blob Java

1---
2name: azure-storage-blob-java
3description: Build blob storage applications with Azure Storage Blob SDK for Java. Use when uploading, downloading, or managing files in Azure Blob Storage, working with containers, or implementing streaming data operations.
4package: com.azure:azure-storage-blob
5---
6 
7# Azure Storage Blob SDK for Java
8 
9Build blob storage applications using the Azure Storage Blob SDK for Java.
10 
11## Installation
12 
13```xml
14<dependency>
15    <groupId>com.azure</groupId>
16    <artifactId>azure-storage-blob</artifactId>
17    <version>12.33.0</version>
18</dependency>
19```
20 
21## Client Creation
22 
23### BlobServiceClient
24 
25```java
26import com.azure.storage.blob.BlobServiceClient;
27import com.azure.storage.blob.BlobServiceClientBuilder;
28 
29// With SAS token
30BlobServiceClient serviceClient = new BlobServiceClientBuilder()
31    .endpoint("<storage-account-url>")
32    .sasToken("<sas-token>")
33    .buildClient();
34 
35// With connection string
36BlobServiceClient serviceClient = new BlobServiceClientBuilder()
37    .connectionString("<connection-string>")
38    .buildClient();
39```
40 
41### With DefaultAzureCredential
42 
43```java
44import com.azure.identity.DefaultAzureCredentialBuilder;
45 
46BlobServiceClient serviceClient = new BlobServiceClientBuilder()
47    .endpoint("<storage-account-url>")
48    .credential(new DefaultAzureCredentialBuilder().build())
49    .buildClient();
50```
51 
52### BlobContainerClient
53 
54```java
55import com.azure.storage.blob.BlobContainerClient;
56 
57// From service client
58BlobContainerClient containerClient = serviceClient.getBlobContainerClient("mycontainer");
59 
60// Direct construction
61BlobContainerClient containerClient = new BlobContainerClientBuilder()
62    .connectionString("<connection-string>")
63    .containerName("mycontainer")
64    .buildClient();
65```
66 
67### BlobClient
68 
69```java
70import com.azure.storage.blob.BlobClient;
71 
72// From container client
73BlobClient blobClient = containerClient.getBlobClient("myblob.txt");
74 
75// With directory structure
76BlobClient blobClient = containerClient.getBlobClient("folder/subfolder/myblob.txt");
77 
78// Direct construction
79BlobClient blobClient = new BlobClientBuilder()
80    .connectionString("<connection-string>")
81    .containerName("mycontainer")
82    .blobName("myblob.txt")
83    .buildClient();
84```
85 
86## Core Patterns
87 
88### Create Container
89 
90```java
91// Create container
92serviceClient.createBlobContainer("mycontainer");
93 
94// Create if not exists
95BlobContainerClient container = serviceClient.createBlobContainerIfNotExists("mycontainer");
96 
97// From container client
98containerClient.create();
99containerClient.createIfNotExists();
100```
101 
102### Upload Data
103 
104```java
105import com.azure.core.util.BinaryData;
106 
107// Upload string
108String data = "Hello, Azure Blob Storage!";
109blobClient.upload(BinaryData.fromString(data));
110 
111// Upload with overwrite
112blobClient.upload(BinaryData.fromString(data), true);
113```
114 
115### Upload from File
116 
117```java
118blobClient.uploadFromFile("local-file.txt");
119 
120// With overwrite
121blobClient.uploadFromFile("local-file.txt", true);
122```
123 
124### Upload from Stream
125 
126```java
127import com.azure.storage.blob.specialized.BlockBlobClient;
128 
129BlockBlobClient blockBlobClient = blobClient.getBlockBlobClient();
130 
131try (ByteArrayInputStream dataStream = new ByteArrayInputStream(data.getBytes())) {
132    blockBlobClient.upload(dataStream, data.length());
133}
134```
135 
136### Upload with Options
137 
138```java
139import com.azure.storage.blob.models.BlobHttpHeaders;
140import com.azure.storage.blob.options.BlobParallelUploadOptions;
141 
142BlobHttpHeaders headers = new BlobHttpHeaders()
143    .setContentType("text/plain")
144    .setCacheControl("max-age=3600");
145 
146Map<String, String> metadata = Map.of("author", "john", "version", "1.0");
147 
148try (InputStream stream = new FileInputStream("large-file.bin")) {
149    BlobParallelUploadOptions options = new BlobParallelUploadOptions(stream)
150        .setHeaders(headers)
151        .setMetadata(metadata);
152    
153    blobClient.uploadWithResponse(options, null, Context.NONE);
154}
155```
156 
157### Upload if Not Exists
158 
159```java
160import com.azure.storage.blob.models.BlobRequestConditions;
161 
162BlobParallelUploadOptions options = new BlobParallelUploadOptions(inputStream, length)
163    .setRequestConditions(new BlobRequestConditions().setIfNoneMatch("*"));
164 
165blobClient.uploadWithResponse(options, null, Context.NONE);
166```
167 
168### Download Data
169 
170```java
171// Download to BinaryData
172BinaryData content = blobClient.downloadContent();
173String text = content.toString();
174 
175// Download to file
176blobClient.downloadToFile("downloaded-file.txt");
177```
178 
179### Download to Stream
180 
181```java
182try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
183    blobClient.downloadStream(outputStream);
184    byte[] data = outputStream.toByteArray();
185}
186```
187 
188### Download with InputStream
189 
190```java
191import com.azure.storage.blob.specialized.BlobInputStream;
192 
193try (BlobInputStream blobIS = blobClient.openInputStream()) {
194    byte[] buffer = new byte[1024];
195    int bytesRead;
196    while ((bytesRead = blobIS.read(buffer)) != -1) {
197        // Process buffer
198    }
199}
200```
201 
202### Upload via OutputStream
203 
204```java
205import com.azure.storage.blob.specialized.BlobOutputStream;
206 
207try (BlobOutputStream blobOS = blobClient.getBlockBlobClient().getBlobOutputStream()) {
208    blobOS.write("Data to upload".getBytes());
209}
210```
211 
212### List Blobs
213 
214```java
215import com.azure.storage.blob.models.BlobItem;
216 
217// List all blobs
218for (BlobItem blobItem : containerClient.listBlobs()) {
219    System.out.println("Blob: " + blobItem.getName());
220}
221 
222// List with prefix (virtual directory)
223import com.azure.storage.blob.models.ListBlobsOptions;
224 
225ListBlobsOptions options = new ListBlobsOptions().setPrefix("folder/");
226for (BlobItem blobItem : containerClient.listBlobs(options, null)) {
227    System.out.println("Blob: " + blobItem.getName());
228}
229```
230 
231### List Blobs by Hierarchy
232 
233```java
234import com.azure.storage.blob.models.BlobListDetails;
235 
236String delimiter = "/";
237ListBlobsOptions options = new ListBlobsOptions()
238    .setPrefix("data/")
239    .setDetails(new BlobListDetails().setRetrieveMetadata(true));
240 
241for (BlobItem item : containerClient.listBlobsByHierarchy(delimiter, options, null)) {
242    if (item.isPrefix()) {
243        System.out.println("Directory: " + item.getName());
244    } else {
245        System.out.println("Blob: " + item.getName());
246    }
247}
248```
249 
250### Delete Blob
251 
252```java
253blobClient.delete();
254 
255// Delete if exists
256blobClient.deleteIfExists();
257 
258// Delete with snapshots
259import com.azure.storage.blob.models.DeleteSnapshotsOptionType;
260blobClient.deleteWithResponse(DeleteSnapshotsOptionType.INCLUDE, null, null, Context.NONE);
261```
262 
263### Copy Blob
264 
265```java
266import com.azure.storage.blob.models.BlobCopyInfo;
267import com.azure.core.util.polling.SyncPoller;
268 
269// Async copy (for large blobs or cross-account)
270SyncPoller<BlobCopyInfo, Void> poller = blobClient.beginCopy("<source-blob-url>", Duration.ofSeconds(1));
271poller.waitForCompletion();
272 
273// Sync copy from URL (for same account)
274blobClient.copyFromUrl("<source-blob-url>");
275```
276 
277### Generate SAS Token
278 
279```java
280import com.azure.storage.blob.sas.*;
281import java.time.OffsetDateTime;
282 
283// Blob-level SAS
284BlobSasPermission permissions = new BlobSasPermission().setReadPermission(true);
285OffsetDateTime expiry = OffsetDateTime.now().plusDays(1);
286 
287BlobServiceSasSignatureValues sasValues = new BlobServiceSasSignatureValues(expiry, permissions);
288String sasToken = blobClient.generateSas(sasValues);
289 
290// Container-level SAS
291BlobContainerSasPermission containerPermissions = new BlobContainerSasPermission()
292    .setReadPermission(true)
293    .setListPermission(true);
294    
295BlobServiceSasSignatureValues containerSasValues = new BlobServiceSasSignatureValues(expiry, containerPermissions);
296String containerSas = containerClient.generateSas(containerSasValues);
297```
298 
299### Blob Properties and Metadata
300 
301```java
302import com.azure.storage.blob.models.BlobProperties;
303 
304// Get properties
305BlobProperties properties = blobClient.getProperties();
306System.out.println("Size: " + properties.getBlobSize());
307System.out.println("Content-Type: " + properties.getContentType());
308System.out.println("Last Modified: " + properties.getLastModified());
309 
310// Set metadata
311Map<String, String> metadata = Map.of("key1", "value1", "key2", "value2");
312blobClient.setMetadata(metadata);
313 
314// Set HTTP headers
315BlobHttpHeaders headers = new BlobHttpHeaders()
316    .setContentType("application/json")
317    .setCacheControl("max-age=86400");
318blobClient.setHttpHeaders(headers);
319```
320 
321### Lease Blob
322 
323```java
324import com.azure.storage.blob.specialized.BlobLeaseClient;
325import com.azure.storage.blob.specialized.BlobLeaseClientBuilder;
326 
327BlobLeaseClient leaseClient = new BlobLeaseClientBuilder()
328    .blobClient(blobClient)
329    .buildClient();
330 
331// Acquire lease (-1 for infinite)
332String leaseId = leaseClient.acquireLease(60);
333 
334// Renew lease
335leaseClient.renewLease();
336 
337// Release lease
338leaseClient.releaseLease();
339```
340 
341## Error Handling
342 
343```java
344import com.azure.storage.blob.models.BlobStorageException;
345 
346try {
347    blobClient.download(outputStream);
348} catch (BlobStorageException e) {
349    System.out.println("Status: " + e.getStatusCode());
350    System.out.println("Error code: " + e.getErrorCode());
351    // 404 = Blob not found
352    // 409 = Conflict (lease, etc.)
353}
354```
355 
356## Proxy Configuration
357 
358```java
359import com.azure.core.http.ProxyOptions;
360import com.azure.core.http.netty.NettyAsyncHttpClientBuilder;
361import java.net.InetSocketAddress;
362 
363ProxyOptions proxyOptions = new ProxyOptions(
364    ProxyOptions.Type.HTTP,
365    new InetSocketAddress("localhost", 8888));
366 
367BlobServiceClient client = new BlobServiceClientBuilder()
368    .endpoint("<endpoint>")
369    .sasToken("<sas-token>")
370    .httpClient(new NettyAsyncHttpClientBuilder().proxy(proxyOptions).build())
371    .buildClient();
372```
373 
374## Environment Variables
375 
376```bash
377AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
378AZURE_STORAGE_ACCOUNT_URL=https://<account>.blob.core.windows.net
379```
380 
381## Trigger Phrases
382 
383- "Azure Blob Storage Java"
384- "upload download blob"
385- "blob container SDK"
386- "storage streaming"
387- "SAS token generation"
388- "blob metadata properties"
389