Sync APIs with S3 specification

Signed-off-by: Bala.FA <[email protected]>

Author: balamurugana

api/src/main/java/io/minio/BaseS3Client.java

@@ -413,6 +413,10 @@ private void onResponse(final Response response) throws IOException {
                       code = result[0];
                       message = result[1];
                       break;
+                    case 403:
+                      code = "AccessDenied";
+                      message = "Access denied";
+                      break;
                     case 404:
                       if (s3request.object() != null) {
                         code = "NoSuchKey";
@@ -425,8 +429,8 @@ private void onResponse(final Response response) throws IOException {
                         message = "Request resource not found";
                       }
                       break;
-                    case 501:
                     case 405:
+                    case 501:
                       code = "MethodNotAllowed";
                       message = "The specified method is not allowed against this resource";
                       break;
@@ -439,10 +443,6 @@ private void onResponse(final Response response) throws IOException {
                         message = "Request resource conflicts";
                       }
                       break;
-                    case 403:
-                      code = "AccessDenied";
-                      message = "Access denied";
-                      break;
                     case 412:
                       code = "PreconditionFailed";
                       message = "At least one of the preconditions you specified did not hold";
@@ -664,13 +664,18 @@ public CompletableFuture<AbortMultipartUploadResponse> abortMultipartUpload(
   public CompletableFuture<ObjectWriteResponse> completeMultipartUpload(
       CompleteMultipartUploadArgs args) {
     checkArgs(args);
+    args.validateSsec(baseUrl.isHttps());
     Http.Body body = null;
     try {
       body = new Http.Body(new CompleteMultipartUpload(args.parts()), null, null, null);
     } catch (MinioException e) {
       return Utils.failedFuture(e);
     }
-    return executePostAsync(args, null, new Http.QueryParameters(UPLOAD_ID, args.uploadId()), body)
+    return executePostAsync(
+            args,
+            args.ssec() == null ? null : args.ssec().headers(),
+            new Http.QueryParameters(UPLOAD_ID, args.uploadId()),
+            body)
         .thenApply(
             response -> {
               try {
@@ -802,7 +807,7 @@ public CompletableFuture<GenericResponse> createBucket(CreateBucketArgs args) {
     if (locationConstraint.equals(Http.US_EAST_1)) {
       config =
           new CreateBucketConfiguration(
-              locationConstraint, args.locationConfig(), args.bucketConfig());
+              locationConstraint, args.locationConfig(), args.bucketConfig(), args.tags());
     }
 
     Http.Body body = null;
@@ -951,6 +956,20 @@ public CompletableFuture<String> getBucketLocation(GetBucketLocationArgs args) {
             });
   }
 
+  /**
+   * Do <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html">HeadBucket S3
+   * API</a> asynchronously.
+   *
+   * @param args {@link HeadBucketArgs} object.
+   * @return {@link CompletableFuture}&lt;{@link HeadBucketResponse}&gt; object.
+   */
+  public CompletableFuture<HeadBucketResponse> headBucket(HeadBucketArgs args) {
+    checkArgs(args);
+    return executeHeadAsync(args, null, null)
+        .thenApply(
+            response -> new HeadBucketResponse(response.headers(), args.bucket(), args.region()));
+  }
+
   /**
    * Do <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html">HeadObject S3
    * API</a> asynchronously.

api/src/main/java/io/minio/BucketExistsArgs.java

@@ -17,11 +17,11 @@
 package io.minio;
 
 /** Arguments of {@link MinioAsyncClient#bucketExists} and {@link MinioClient#bucketExists}. */
-public class BucketExistsArgs extends BucketArgs {
+public class BucketExistsArgs extends HeadBucketBaseArgs {
   public static Builder builder() {
     return new Builder();
   }
 
   /** Builder of {@link BucketExistsArgs}. */
-  public static final class Builder extends BucketArgs.Builder<Builder, BucketExistsArgs> {}
+  public static final class Builder extends HeadBucketBaseArgs.Builder<Builder, BucketExistsArgs> {}
 }

api/src/main/java/io/minio/CompleteMultipartUploadArgs.java

@@ -24,6 +24,7 @@
 public class CompleteMultipartUploadArgs extends ObjectArgs {
   private String uploadId;
   private Part[] parts;
+  private ServerSideEncryption.CustomerKey ssec;
 
   protected CompleteMultipartUploadArgs() {}
 
@@ -37,6 +38,9 @@ public CompleteMultipartUploadArgs(PutObjectBaseArgs args, String uploadId, Part
     super(args);
     this.uploadId = uploadId;
     this.parts = parts;
+    if (args.sse() != null && args.sse() instanceof ServerSideEncryption.CustomerKey) {
+      this.ssec = (ServerSideEncryption.CustomerKey) args.sse();
+    }
   }
 
   public String uploadId() {
@@ -47,6 +51,14 @@ public Part[] parts() {
     return parts;
   }
 
+  public ServerSideEncryption.CustomerKey ssec() {
+    return ssec;
+  }
+
+  public void validateSsec(boolean isHttps) {
+    checkSse(ssec, isHttps);
+  }
+
   public static Builder builder() {
     return new Builder();
   }
@@ -72,6 +84,11 @@ public Builder parts(Part[] parts) {
       operations.add(args -> args.parts = parts);
       return this;
     }
+
+    public Builder ssec(ServerSideEncryption.CustomerKey ssec) {
+      operations.add(args -> args.ssec = ssec);
+      return this;
+    }
   }
 
   @Override
@@ -80,11 +97,13 @@ public boolean equals(Object o) {
     if (!(o instanceof CompleteMultipartUploadArgs)) return false;
     if (!super.equals(o)) return false;
     CompleteMultipartUploadArgs that = (CompleteMultipartUploadArgs) o;
-    return Objects.equals(uploadId, that.uploadId) && Arrays.equals(parts, that.parts);
+    return Objects.equals(uploadId, that.uploadId)
+        && Arrays.equals(parts, that.parts)
+        && Objects.equals(ssec, that.ssec);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(super.hashCode(), uploadId, parts);
+    return Objects.hash(super.hashCode(), uploadId, parts, ssec);
   }
 }

api/src/main/java/io/minio/CreateBucketBaseArgs.java

@@ -17,13 +17,15 @@
 package io.minio;
 
 import io.minio.messages.CreateBucketConfiguration;
+import io.minio.messages.Tags;
 import java.util.Objects;
 
 /** Common arguments of {@link CreateBucketArgs} and {@link MakeBucketArgs}. */
 public abstract class CreateBucketBaseArgs extends BucketArgs {
   protected boolean objectLock;
   protected CreateBucketConfiguration.Location locationConfig;
   protected CreateBucketConfiguration.Bucket bucket;
+  protected Tags tags;
 
   protected CreateBucketBaseArgs() {}
 
@@ -32,6 +34,7 @@ protected CreateBucketBaseArgs(CreateBucketBaseArgs args) {
     this.objectLock = args.objectLock;
     this.locationConfig = args.locationConfig;
     this.bucket = args.bucket;
+    this.tags = args.tags;
   }
 
   public boolean objectLock() {
@@ -46,6 +49,10 @@ public CreateBucketConfiguration.Bucket bucketConfig() {
     return bucket;
   }
 
+  public Tags tags() {
+    return tags;
+  }
+
   /** Base argument builder of {@link CreateBucketBaseArgs}. */
   @SuppressWarnings("unchecked") // Its safe to type cast to B as B is inherited by this class
   public abstract static class Builder<B extends Builder<B, A>, A extends CreateBucketBaseArgs>
@@ -69,6 +76,11 @@ public B bucketConfig(CreateBucketConfiguration.Bucket bucket) {
       operations.add(args -> args.bucket = bucket);
       return (B) this;
     }
+
+    public B tags(Tags tags) {
+      operations.add(args -> args.tags = tags);
+      return (B) this;
+    }
   }
 
   @Override
@@ -79,11 +91,12 @@ public boolean equals(Object o) {
     CreateBucketBaseArgs that = (CreateBucketBaseArgs) o;
     return objectLock == that.objectLock
         && Objects.equals(locationConfig, that.locationConfig)
-        && Objects.equals(bucket, that.bucket);
+        && Objects.equals(bucket, that.bucket)
+        && Objects.equals(tags, that.tags);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(super.hashCode(), objectLock, locationConfig, bucket);
+    return Objects.hash(super.hashCode(), objectLock, locationConfig, bucket, tags);
   }
 }

api/src/main/java/io/minio/DownloadObjectArgs.java

@@ -16,6 +16,7 @@
 
 package io.minio;
 
+import java.time.ZonedDateTime;
 import java.util.Objects;
 
 /**
@@ -25,6 +26,10 @@
 public class DownloadObjectArgs extends ObjectReadArgs {
   private String filename;
   private boolean overwrite;
+  protected String matchETag;
+  protected String notMatchETag;
+  protected ZonedDateTime modifiedSince;
+  protected ZonedDateTime unmodifiedSince;
 
   public String filename() {
     return filename;
@@ -34,6 +39,22 @@ public boolean overwrite() {
     return overwrite;
   }
 
+  public String matchETag() {
+    return matchETag;
+  }
+
+  public String notMatchETag() {
+    return notMatchETag;
+  }
+
+  public ZonedDateTime modifiedSince() {
+    return modifiedSince;
+  }
+
+  public ZonedDateTime unmodifiedSince() {
+    return unmodifiedSince;
+  }
+
   public static Builder builder() {
     return new Builder();
   }
@@ -54,6 +75,28 @@ public Builder overwrite(boolean flag) {
       operations.add(args -> args.overwrite = flag);
       return this;
     }
+
+    public Builder matchETag(String etag) {
+      Utils.validateNullOrNotEmptyString(etag, "etag");
+      operations.add(args -> args.matchETag = etag);
+      return this;
+    }
+
+    public Builder notMatchETag(String etag) {
+      Utils.validateNullOrNotEmptyString(etag, "etag");
+      operations.add(args -> args.notMatchETag = etag);
+      return this;
+    }
+
+    public Builder modifiedSince(ZonedDateTime modifiedTime) {
+      operations.add(args -> args.modifiedSince = modifiedTime);
+      return this;
+    }
+
+    public Builder unmodifiedSince(ZonedDateTime unmodifiedTime) {
+      operations.add(args -> args.unmodifiedSince = unmodifiedTime);
+      return this;
+    }
   }
 
   @Override
@@ -62,12 +105,23 @@ public boolean equals(Object o) {
     if (!(o instanceof DownloadObjectArgs)) return false;
     if (!super.equals(o)) return false;
     DownloadObjectArgs that = (DownloadObjectArgs) o;
-    if (!Objects.equals(filename, that.filename)) return false;
-    return overwrite == that.overwrite;
+    return Objects.equals(filename, that.filename)
+        && overwrite == that.overwrite
+        && Objects.equals(matchETag, that.matchETag)
+        && Objects.equals(notMatchETag, that.notMatchETag)
+        && Objects.equals(modifiedSince, that.modifiedSince)
+        && Objects.equals(unmodifiedSince, that.unmodifiedSince);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(super.hashCode(), filename, overwrite);
+    return Objects.hash(
+        super.hashCode(),
+        filename,
+        overwrite,
+        matchETag,
+        notMatchETag,
+        modifiedSince,
+        unmodifiedSince);
   }
 }

api/src/main/java/io/minio/GenericUploadResponse.java

@@ -18,11 +18,13 @@
 
 import io.minio.messages.CompleteMultipartUploadResult;
 import io.minio.messages.CopyObjectResult;
+import java.time.ZonedDateTime;
 import okhttp3.Headers;
 
 /** Common response of {@link ObjectWriteResponse} and {@link PutObjectFanOutResponse}. */
 public class GenericUploadResponse extends GenericResponse {
   private String etag;
+  private ZonedDateTime lastModified;
   private String checksumCRC32;
   private String checksumCRC32C;
   private String checksumCRC64NVME;
@@ -53,6 +55,7 @@ public GenericUploadResponse(
       CopyObjectResult result) {
     super(headers, bucket, region, object);
     this.etag = etag;
+    this.lastModified = result.lastModified();
     if (result != null) {
       this.checksumType = result.checksumType();
       this.checksumCRC32 = result.checksumCRC32();
@@ -86,6 +89,10 @@ public String etag() {
     return etag;
   }
 
+  public ZonedDateTime lastModified() {
+    return lastModified;
+  }
+
   public String checksumCRC32() {
     return checksumCRC32;
   }

api/src/main/java/io/minio/HeadBucketArgs.java

@@ -0,0 +1,27 @@
+/*
+ * MinIO Java SDK for Amazon S3 Compatible Cloud Storage, (C) 2025 MinIO, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.minio;
+
+/** Arguments of {@link BaseS3Client#headBucket}. */
+public class HeadBucketArgs extends HeadBucketBaseArgs {
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  /** Builder of {@link HeadBucketArgs}. */
+  public static final class Builder extends HeadBucketBaseArgs.Builder<Builder, HeadBucketArgs> {}
+}