blobstore: Implement the DoesBucketExist for Blob

blob/blob-ali/src/main/java/com/salesforce/multicloudj/blob/ali/AliBlobStore.java

@@ -475,6 +475,24 @@ protected boolean doDoesObjectExist(String key, String versionId) {
         return ossClient.doesObjectExist(transformer.toMetadataRequest(key, versionId));
     }
 
+    /**
+     * Determines if the bucket exists
+     * @return Returns true if the bucket exists. Returns false if it doesn't exist.
+     */
+    @Override
+    protected boolean doDoesBucketExist() {
+        try {
+            return ossClient.doesBucketExist(bucket);
+        } catch (ServiceException e) {
+            if ("NoSuchBucket".equals(e.getErrorCode())) {
+                return false;
+            }
+            throw new SubstrateSdkException("Failed to check bucket existence", e);
+        } catch (ClientException e) {
+            throw new SubstrateSdkException("Failed to check bucket existence", e);
+        }
+    }
+
     /**
      * Closes the underlying OSS client and releases any resources.
      */

blob/blob-ali/src/test/java/com/salesforce/multicloudj/blob/ali/AliBlobStoreTest.java

@@ -5,6 +5,7 @@
 import com.aliyun.oss.OSS;
 import com.aliyun.oss.OSSClientBuilder;
 import com.aliyun.oss.OSSException;
+import com.aliyun.oss.ServiceException;
 import com.aliyun.oss.internal.OSSHeaders;
 import com.aliyun.oss.model.AbortMultipartUploadRequest;
 import com.aliyun.oss.model.CompleteMultipartUploadRequest;
@@ -84,12 +85,14 @@
 import java.util.stream.IntStream;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.doThrow;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.mockStatic;
 import static org.mockito.Mockito.times;
@@ -783,6 +786,57 @@ void testDoDoesObjectExist() {
         assertTrue(result);
     }
 
+    @Test
+    void testDoDoesBucketExist() {
+        doReturn(true).when(mockOssClient).doesBucketExist("bucket-1");
+
+        boolean result = ali.doDoesBucketExist();
+
+        verify(mockOssClient, times(1)).doesBucketExist("bucket-1");
+        assertTrue(result);
+    }
+
+    @Test
+    void testDoDoesBucketExist_BucketDoesNotExist() {
+        doReturn(false).when(mockOssClient).doesBucketExist("bucket-1");
+
+        boolean result = ali.doDoesBucketExist();
+
+        verify(mockOssClient, times(1)).doesBucketExist("bucket-1");
+        assertFalse(result);
+    }
+
+    @Test
+    void testDoDoesBucketExist_ThrowsNoSuchBucketException() {
+        com.aliyun.oss.ServiceException serviceException = mock(com.aliyun.oss.ServiceException.class);
+        doReturn("NoSuchBucket").when(serviceException).getErrorCode();
+        doThrow(serviceException).when(mockOssClient).doesBucketExist("bucket-1");
+
+        boolean result = ali.doDoesBucketExist();
+
+        verify(mockOssClient, times(1)).doesBucketExist("bucket-1");
+        assertFalse(result);
+    }
+
+    @Test
+    void testDoDoesBucketExist_ThrowsOtherServiceException() {
+        com.aliyun.oss.ServiceException serviceException = mock(com.aliyun.oss.ServiceException.class);
+        doReturn("AccessDenied").when(serviceException).getErrorCode();
+        doThrow(serviceException).when(mockOssClient).doesBucketExist("bucket-1");
+
+        assertThrows(com.salesforce.multicloudj.common.exceptions.SubstrateSdkException.class, () -> ali.doDoesBucketExist());
+        verify(mockOssClient, times(1)).doesBucketExist("bucket-1");
+    }
+
+    @Test
+    void testDoDoesBucketExist_ThrowsClientException() {
+        ClientException clientException = mock(ClientException.class);
+        doThrow(clientException).when(mockOssClient).doesBucketExist("bucket-1");
+
+        assertThrows(com.salesforce.multicloudj.common.exceptions.SubstrateSdkException.class, () -> ali.doDoesBucketExist());
+        verify(mockOssClient, times(1)).doesBucketExist("bucket-1");
+    }
+
     private UploadRequest getTestUploadRequest() {
         Map<String, String> metadata = Map.of("key-1", "value-1");
         Map<String, String> tags = Map.of("tag-1", "tag-value-1");

blob/blob-aws/src/main/java/com/salesforce/multicloudj/blob/aws/AwsBlobStore.java

@@ -51,6 +51,7 @@
 import software.amazon.awssdk.services.s3.model.GetObjectRequest;
 import software.amazon.awssdk.services.s3.model.GetObjectResponse;
 import software.amazon.awssdk.services.s3.model.GetObjectTaggingResponse;
+import software.amazon.awssdk.services.s3.model.HeadBucketRequest;
 import software.amazon.awssdk.services.s3.model.HeadObjectRequest;
 import software.amazon.awssdk.services.s3.model.HeadObjectResponse;
 import software.amazon.awssdk.services.s3.model.ListObjectsV2Request;
@@ -488,6 +489,20 @@ protected boolean doDoesObjectExist(String key, String versionId) {
         }
     }
 
+    @Override
+    protected boolean doDoesBucketExist() {
+        try {
+            s3Client.headBucket(builder -> builder.bucket(bucket));
+            return true;
+        }
+        catch(S3Exception e) {
+            if (e.statusCode() == 404) {
+                return false;
+            }
+            throw e;
+        }
+    }
+
     /**
      * Closes the underlying S3 client and releases any resources.
      */

blob/blob-aws/src/main/java/com/salesforce/multicloudj/blob/aws/async/AwsAsyncBlobStore.java

@@ -403,6 +403,20 @@ protected CompletableFuture<Boolean> doDoesObjectExist(String key, String versio
                 });
     }
 
+    @Override
+    protected CompletableFuture<Boolean> doDoesBucketExist() {
+        return client
+                .headBucket(builder -> builder.bucket(bucket))
+                .thenApply(response -> true)
+                .exceptionally(e -> {
+                    if (e.getCause() instanceof S3Exception && ((S3Exception) e.getCause()).statusCode() == 404) {
+                        return false;
+                    } else {
+                        throw new SubstrateSdkException("Request failed. Reason=" + e.getMessage(), e);
+                    }
+                });
+    }
+
     /**
      * Closes the underlying S3 async client and transfer manager, releasing any resources.
      */

blob/blob-aws/src/test/java/com/salesforce/multicloudj/blob/aws/AwsBlobStoreTest.java

@@ -59,6 +59,8 @@
 import software.amazon.awssdk.services.s3.model.GetObjectResponse;
 import software.amazon.awssdk.services.s3.model.GetObjectTaggingRequest;
 import software.amazon.awssdk.services.s3.model.GetObjectTaggingResponse;
+import software.amazon.awssdk.services.s3.model.HeadBucketRequest;
+import software.amazon.awssdk.services.s3.model.HeadBucketResponse;
 import software.amazon.awssdk.services.s3.model.HeadObjectRequest;
 import software.amazon.awssdk.services.s3.model.HeadObjectResponse;
 import software.amazon.awssdk.services.s3.model.ListObjectsV2Request;
@@ -1033,6 +1035,25 @@ void testDoDoesObjectExist() {
         assertFalse(result);
     }
 
+    @Test
+    void testDoDoesBucketExist() {
+        HeadBucketResponse mockResponse = mock(HeadBucketResponse.class);
+        when(mockS3Client.headBucket(ArgumentMatchers.<java.util.function.Consumer<HeadBucketRequest.Builder>>any())).thenReturn(mockResponse);
+
+        boolean result = aws.doDoesBucketExist();
+
+        verify(mockS3Client, times(1)).headBucket(ArgumentMatchers.<java.util.function.Consumer<HeadBucketRequest.Builder>>any());
+        assertTrue(result);
+
+        // Verify the error state - bucket doesn't exist (404)
+        S3Exception mockException = mock(S3Exception.class);
+        doReturn(404).when(mockException).statusCode();
+        doThrow(mockException).when(mockS3Client).headBucket(ArgumentMatchers.<java.util.function.Consumer<HeadBucketRequest.Builder>>any());
+
+        result = aws.doDoesBucketExist();
+        assertFalse(result);
+    }
+
     private S3Object mockObject(int index) {
         S3Object mockS3 = mock(S3Object.class);
         when(mockS3.key()).thenReturn("key-" + index);

blob/blob-aws/src/test/java/com/salesforce/multicloudj/blob/aws/async/AwsAsyncBlobStoreTest.java

@@ -70,6 +70,8 @@
 import software.amazon.awssdk.services.s3.model.GetObjectResponse;
 import software.amazon.awssdk.services.s3.model.GetObjectTaggingRequest;
 import software.amazon.awssdk.services.s3.model.GetObjectTaggingResponse;
+import software.amazon.awssdk.services.s3.model.HeadBucketRequest;
+import software.amazon.awssdk.services.s3.model.HeadBucketResponse;
 import software.amazon.awssdk.services.s3.model.HeadObjectRequest;
 import software.amazon.awssdk.services.s3.model.HeadObjectResponse;
 import software.amazon.awssdk.services.s3.model.ListObjectsV2Request;
@@ -136,6 +138,7 @@
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
+import org.mockito.ArgumentMatchers;
 import static org.mockito.Mockito.doAnswer;
 import static org.mockito.Mockito.doReturn;
 import static org.mockito.Mockito.mock;
@@ -1133,6 +1136,30 @@ void testDoDoesObjectExist() throws ExecutionException, InterruptedException {
         assertInstanceOf(SubstrateSdkException.class, assertThrows(ExecutionException.class, exceptionalResult::get).getCause());
     }
 
+    @Test
+    void testDoDoesBucketExist() throws ExecutionException, InterruptedException {
+        HeadBucketResponse mockResponse = mock(HeadBucketResponse.class);
+        doReturn(future(mockResponse)).when(mockS3Client).headBucket(ArgumentMatchers.<java.util.function.Consumer<HeadBucketRequest.Builder>>any());
+
+        boolean result = aws.doDoesBucketExist().get();
+
+        verify(mockS3Client, times(1)).headBucket(ArgumentMatchers.<java.util.function.Consumer<HeadBucketRequest.Builder>>any());
+        assertTrue(result);
+
+        // Verify the error state - bucket doesn't exist (404)
+        S3Exception mockException = mock(S3Exception.class);
+        doReturn(404).when(mockException).statusCode();
+        doReturn(CompletableFuture.failedFuture(mockException)).when(mockS3Client).headBucket(ArgumentMatchers.<java.util.function.Consumer<HeadBucketRequest.Builder>>any());
+        result = aws.doDoesBucketExist().get();
+        assertFalse(result);
+
+        // Verify the unexpected error state
+        doReturn(CompletableFuture.failedFuture(mock(RuntimeException.class))).when(mockS3Client).headBucket(ArgumentMatchers.<java.util.function.Consumer<HeadBucketRequest.Builder>>any());
+        var exceptionalResult = aws.doDoesBucketExist();
+        assertTrue(exceptionalResult.isCompletedExceptionally());
+        assertInstanceOf(SubstrateSdkException.class, assertThrows(ExecutionException.class, exceptionalResult::get).getCause());
+    }
+
     @Test
     void doDownloadDirectory() throws ExecutionException, InterruptedException {
 

blob/blob-aws/src/test/resources/mappings/head-pgwz6txhaw.json

@@ -0,0 +1,21 @@
+{
+  "id" : "6c44e456-44f3-477e-9866-b4713335e4cb",
+  "name" : "java-bucket-does-not-exist",
+  "request" : {
+    "url" : "/java-bucket-does-not-exist",
+    "method" : "HEAD"
+  },
+  "response" : {
+    "status" : 404,
+    "headers" : {
+      "Server" : "AmazonS3",
+      "x-amz-request-id" : "S25MYAZ5WTF51AJ8",
+      "x-amz-id-2" : "4yw9URr1CZ7CQpeqEif9BaRFIRyp/WxIQiYWQ6eDdZRoT8CJXtnoUhRf3u6WRkF8OYZTtjXLm/g6owSCjFfRE7F/0Ny35DW1LumP474xCbk=",
+      "Date" : "Wed, 10 Dec 2025 17:44:21 GMT",
+      "Content-Type" : "application/xml"
+    }
+  },
+  "uuid" : "6c44e456-44f3-477e-9866-b4713335e4cb",
+  "persistent" : true,
+  "insertionIndex" : 595
+}

blob/blob-aws/src/test/resources/mappings/head-ruowftbegm.json

@@ -0,0 +1,24 @@
+{
+  "id" : "5abebd0a-9030-4e7b-91aa-1409334a4b6b",
+  "name" : "chameleon-jcloud",
+  "request" : {
+    "url" : "/chameleon-jcloud",
+    "method" : "HEAD"
+  },
+  "response" : {
+    "status" : 200,
+    "headers" : {
+      "Server" : "AmazonS3",
+      "x-amz-access-point-alias" : "false",
+      "x-amz-bucket-arn" : "arn:aws:s3:::chameleon-jcloud",
+      "x-amz-request-id" : "JTCB60A5F2ERKBDM",
+      "x-amz-id-2" : "VBMYlZ3W9WACjGa0VL6cjK5tNsgDdM6at9KorprY5u9IPJg1A+z4PCWxSDjzdkWQME2f9Sh/NK4=",
+      "x-amz-bucket-region" : "us-west-2",
+      "Date" : "Wed, 10 Dec 2025 17:43:54 GMT",
+      "Content-Type" : "application/xml"
+    }
+  },
+  "uuid" : "5abebd0a-9030-4e7b-91aa-1409334a4b6b",
+  "persistent" : true,
+  "insertionIndex" : 594
+}

blob/blob-client/src/main/java/com/salesforce/multicloudj/blob/async/client/AsyncBucketClient.java

@@ -387,6 +387,17 @@ public CompletableFuture<Boolean> doesObjectExist(String key, String versionId)
                 .exceptionally(this::handleException);
     }
 
+    /**
+     * Determines if the bucket exists
+     * @return Returns true if the bucket exists. Returns false if it doesn't exist.
+     * @throws SubstrateSdkException Thrown if the operation fails
+     */
+    public CompletableFuture<Boolean> doesBucketExist() {
+        return blobStore
+                .doesBucketExist()
+                .exceptionally(this::handleException);
+    }
+
     /**
      * Uploads the directory content to substrate-specific Blob storage
      * Note: Specifying the contentLength in the UploadRequest can dramatically improve upload efficiency

blob/blob-client/src/main/java/com/salesforce/multicloudj/blob/async/driver/AbstractAsyncBlobStore.java

@@ -280,6 +280,14 @@ public CompletableFuture<Boolean> doesObjectExist(String key, String versionId)
         return doDoesObjectExist(key, versionId);
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public CompletableFuture<Boolean> doesBucketExist() {
+        return doDoesBucketExist();
+    }
+
     /**
      * {@inheritDoc}
      */
@@ -352,6 +360,8 @@ public CompletableFuture<Void> deleteDirectory(String prefix) {
 
     protected abstract CompletableFuture<Boolean> doDoesObjectExist(String key, String versionId);
 
+    protected abstract CompletableFuture<Boolean> doDoesBucketExist();
+
     protected abstract CompletableFuture<DirectoryDownloadResponse> doDownloadDirectory(DirectoryDownloadRequest directoryDownloadRequest);
 
     protected abstract CompletableFuture<DirectoryUploadResponse> doUploadDirectory(DirectoryUploadRequest directoryUploadRequest);

blob/blob-client/src/main/java/com/salesforce/multicloudj/blob/async/driver/AsyncBlobStore.java

@@ -247,6 +247,12 @@ public interface AsyncBlobStore extends SdkService, AutoCloseable {
      */
     CompletableFuture<Boolean> doesObjectExist(String key, String versionId);
 
+    /**
+     * Determines if the bucket exists
+     * @return Returns true if the bucket exists. Returns false if it doesn't exist.
+     */
+    CompletableFuture<Boolean> doesBucketExist();
+
     /**
      * Downloads the directory content from substrate-specific Blob storage.
      *

blob/blob-client/src/main/java/com/salesforce/multicloudj/blob/async/driver/BlobStoreAsyncBridge.java

@@ -220,6 +220,11 @@ public CompletableFuture<Boolean> doesObjectExist(String key, String versionId)
         return CompletableFuture.supplyAsync(() -> blobStore.doesObjectExist(key, versionId), executorService);
     }
 
+    @Override
+    public CompletableFuture<Boolean> doesBucketExist() {
+        return CompletableFuture.supplyAsync(() -> blobStore.doesBucketExist(), executorService);
+    }
+
     @Override
     public Class<? extends SubstrateSdkException> getException(Throwable t) {
         return blobStore.getException(t);

blob/blob-client/src/main/java/com/salesforce/multicloudj/blob/client/BucketClient.java

@@ -484,6 +484,21 @@ public boolean doesObjectExist(String key, String versionId) {
         }
     }
 
+    /**
+     * Determines if the bucket exists
+     * @return Returns true if the bucket exists. Returns false if it doesn't exist.
+     * @throws SubstrateSdkException Thrown if the operation fails
+     */
+    public boolean doesBucketExist() {
+        try {
+            return blobStore.doesBucketExist();
+        } catch (Throwable t) {
+            Class<? extends SubstrateSdkException> exception = blobStore.getException(t);
+            ExceptionHandler.handleAndPropagate(exception, t);
+            return false;
+        }
+    }
+
     /**
      * Closes the underlying blob store and releases any resources.
      */