Make bucket with builder

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

@@ -0,0 +1,78 @@
+/*
+ * MinIO Java SDK for Amazon S3 Compatible Cloud Storage, (C) 2020 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;
+
+public abstract class BucketArgs {
+  private String name;
+  private String region;
+
+  BucketArgs(Builder<?> builder) {
+    if (builder.name == null) {
+      throw new IllegalArgumentException("null bucket name");
+    }
+
+    // Bucket names cannot be no less than 3 and no more than 63 characters long.
+    if (builder.name.length() < 3 || builder.name.length() > 63) {
+      throw new IllegalArgumentException(
+          builder.name
+              + " : "
+              + "bucket name must be at least 3 and no more than 63 characters long");
+    }
+    // Successive periods in bucket names are not allowed.
+    if (builder.name.contains("..")) {
+      String msg =
+          "bucket name cannot contain successive periods. For more information refer "
+              + "http://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html";
+      throw new IllegalArgumentException(builder.name + " : " + msg);
+    }
+    // Bucket names should be dns compatible.
+    if (!builder.name.matches("^[a-z0-9][a-z0-9\\.\\-]+[a-z0-9]$")) {
+      String msg =
+          "bucket name does not follow Amazon S3 standards. For more information refer "
+              + "http://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html";
+      throw new IllegalArgumentException(builder.name + " : " + msg);
+    }
+    this.name = builder.name;
+    this.region = builder.region;
+  }
+
+  public String bucketName() {
+    return name;
+  }
+
+  public String region() {
+    return region;
+  }
+
+  public abstract static class Builder<T extends Builder<T>> {
+    public String name;
+    public String region;
+
+    @SuppressWarnings("unchecked")
+    public T bucket(String name) {
+      this.name = name;
+
+      return (T) this;
+    }
+
+    @SuppressWarnings("unchecked")
+    public T region(String region) {
+      this.region = region;
+      return (T) this;
+    }
+  }
+}

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

@@ -0,0 +1,55 @@
+/*
+ * MinIO Java SDK for Amazon S3 Compatible Cloud Storage, (C) 2020 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;
+
+public class MakeBucketArgs extends BucketArgs {
+  private final boolean objectLock;
+
+  MakeBucketArgs(Builder builder) {
+    super(builder);
+    this.objectLock = builder.objectLock;
+  }
+
+  public boolean objectLock() {
+    return objectLock;
+  }
+
+  public Builder build() {
+    return new Builder(this);
+  }
+
+  public static final class Builder extends BucketArgs.Builder<Builder> {
+    private boolean objectLock;
+
+    public Builder() {}
+
+    public Builder(MakeBucketArgs args) {
+      this.name = args.bucketName();
+      this.region = args.region();
+      this.objectLock = args.objectLock();
+    }
+
+    public Builder objectLock(boolean objectLock) {
+      this.objectLock = objectLock;
+      return this;
+    }
+
+    public MakeBucketArgs build() throws IllegalArgumentException {
+      return new MakeBucketArgs(this);
+    }
+  }
+}

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

@@ -1957,27 +1957,27 @@ public void getObject(
    * Creates an object by server-side copying data from another object.
    *
    * <pre>Example:{@code
-   * // Copy data from my-source-bucketname/my-objectname to my-bucketname/my-objectname.
+   *  Copy data from my-source-bucketname/my-objectname to my-bucketname/my-objectname.
    * minioClient.copyObject("my-bucketname", "my-objectname", null, null,
    *     "my-source-bucketname", null, null, null);
    *
-   * // Copy data from my-source-bucketname/my-source-objectname to
-   * // my-bucketname/my-objectname.
+   *  Copy data from my-source-bucketname/my-source-objectname to
+   *  my-bucketname/my-objectname.
    * minioClient.copyObject("my-bucketname", "my-objectname", null, null,
    *     "my-source-bucketname", "my-source-objectname", null, null);
    *
-   * // Copy data from my-source-bucketname/my-objectname to my-bucketname/my-objectname
-   * // by server-side encryption.
+   * Copy data from my-source-bucketname/my-objectname to my-bucketname/my-objectname
+   *  by server-side encryption.
    * minioClient.copyObject("my-bucketname", "my-objectname", null, sse,
    *     "my-source-bucketname", null, null, null);
    *
-   * // Copy data from SSE-C encrypted my-source-bucketname/my-objectname to
-   * // my-bucketname/my-objectname.
+   * Copy data from SSE-C encrypted my-source-bucketname/my-objectname to
+   *  my-bucketname/my-objectname.
    * minioClient.copyObject("my-bucketname", "my-objectname", null, null,
    *     "my-source-bucketname", null, srcSsec, null);
    *
-   * // Copy data from my-source-bucketname/my-objectname to my-bucketname/my-objectname
-   * // with user metadata and copy conditions.
+   * Copy data from my-source-bucketname/my-objectname to my-bucketname/my-objectname
+   *  with user metadata and copy conditions.
    * minioClient.copyObject("my-bucketname", "my-objectname", headers, null,
    *     "my-source-bucketname", null, null, conditions);
    * }</pre>
@@ -3263,12 +3263,13 @@ public boolean bucketExists(String bucketName)
    * @throws RegionConflictException thrown to indicate passed region conflict with default region.
    * @throws XmlParserException thrown to indicate XML parsing error.
    */
+  @Deprecated
   public void makeBucket(String bucketName)
       throws ErrorResponseException, IllegalArgumentException, InsufficientDataException,
           InternalException, InvalidBucketNameException, InvalidKeyException,
           InvalidResponseException, IOException, NoSuchAlgorithmException, RegionConflictException,
           XmlParserException {
-    this.makeBucket(bucketName, null, false);
+    this.makeBucket(new MakeBucketArgs.Builder().bucket(bucketName).build());
   }
 
   /**
@@ -3293,12 +3294,13 @@ public void makeBucket(String bucketName)
    * @throws RegionConflictException thrown to indicate passed region conflict with default region.
    * @throws XmlParserException thrown to indicate XML parsing error.
    */
+  @Deprecated
   public void makeBucket(String bucketName, String region)
       throws ErrorResponseException, IllegalArgumentException, InsufficientDataException,
           InternalException, InvalidBucketNameException, InvalidKeyException,
           InvalidResponseException, IOException, NoSuchAlgorithmException, RegionConflictException,
           XmlParserException {
-    this.makeBucket(bucketName, region, false);
+    this.makeBucket(new MakeBucketArgs.Builder().bucket(bucketName).region(region).build());
   }
 
   /**
@@ -3324,13 +3326,54 @@ public void makeBucket(String bucketName, String region)
    * @throws RegionConflictException thrown to indicate passed region conflict with default region.
    * @throws XmlParserException thrown to indicate XML parsing error.
    */
+  @Deprecated
   public void makeBucket(String bucketName, String region, boolean objectLock)
       throws ErrorResponseException, IllegalArgumentException, InsufficientDataException,
           InternalException, InvalidBucketNameException, InvalidKeyException,
           InvalidResponseException, IOException, NoSuchAlgorithmException, RegionConflictException,
           XmlParserException {
-    // If region param is not provided, set it with the one provided by constructor
-    if (region == null) {
+    this.makeBucket(
+        new MakeBucketArgs.Builder()
+            .bucket(bucketName)
+            .region(region)
+            .objectLock(objectLock)
+            .build());
+  }
+
+  /**
+   * Creates a bucket with make bucket arguments.
+   *
+   * <pre>Example:{@code
+   * minioClient.makeBucket(MakeBucketArgs args);
+   * }</pre>
+   *
+   * @param args Object with bucket name, region and lock functionality
+   * @throws ErrorResponseException thrown to indicate S3 service returned an error response.
+   * @throws IllegalArgumentException throws to indicate invalid argument passed.
+   * @throws InsufficientDataException thrown to indicate not enough data available in InputStream.
+   * @throws InternalException thrown to indicate internal library error.
+   * @throws InvalidBucketNameException thrown to indicate invalid bucket name passed.
+   * @throws InvalidKeyException thrown to indicate missing of HMAC SHA-256 library.
+   * @throws InvalidResponseException thrown to indicate S3 service returned invalid or no error
+   *     response.
+   * @throws IOException thrown to indicate I/O error on S3 operation.
+   * @throws NoSuchAlgorithmException thrown to indicate missing of MD5 or SHA-256 digest library.
+   * @throws RegionConflictException thrown to indicate passed region conflict with default region.
+   * @throws XmlParserException thrown to indicate XML parsing error.
+   */
+  public void makeBucket(MakeBucketArgs args)
+      throws InvalidBucketNameException, RegionConflictException, InsufficientDataException,
+          InternalException, InvalidResponseException, InvalidKeyException,
+          NoSuchAlgorithmException, XmlParserException, ErrorResponseException, IOException {
+
+    if (args == null) {
+      throw new IllegalArgumentException("null value is not allowed in arguments");
+    }
+
+    String region = US_EAST_1;
+    if (args.region() != null && !args.region().isEmpty()) {
+      region = args.region();
+    } else if (this.region != null && !this.region.isEmpty()) {
       region = this.region;
     }
 
@@ -3340,22 +3383,18 @@ public void makeBucket(String bucketName, String region, boolean objectLock)
           "passed region conflicts with the one previously specified");
     }
 
-    if (region == null) {
-      region = US_EAST_1;
-    }
-
     CreateBucketConfiguration config = null;
     if (!region.equals(US_EAST_1)) {
       config = new CreateBucketConfiguration(region);
     }
 
     Map<String, String> headerMap = null;
-    if (objectLock) {
+    if (args.objectLock()) {
       headerMap = new HashMap<>();
       headerMap.put("x-amz-bucket-object-lock-enabled", "true");
     }
 
-    Response response = executePut(bucketName, null, region, headerMap, null, config, 0);
+    Response response = executePut(args.bucketName(), null, region, headerMap, null, config, 0);
     response.body().close();
   }
 

api/src/test/java/io/minio/MinioClientTest.java

@@ -302,7 +302,7 @@ public void testInvalidResponse4()
   public void testMakeBucketRegionConflicts()
       throws NoSuchAlgorithmException, IOException, InvalidKeyException, MinioException {
     MinioClient client = new MinioClient("http://play.min.io:9000", "foo", "bar", "us-east-1");
-    client.makeBucket("mybucket", "us-west-2");
+    client.makeBucket(new MakeBucketArgs.Builder().bucket("mybucket").region("us-west-2").build());
     Assert.fail("exception should be thrown");
   }
 

docs/API.md

@@ -645,55 +645,30 @@ for (Result<Item> result : results) {
 }
 ```
 
-<a name="makeBucket"></a>
-### makeBucket(String bucketName)
-`public void makeBucket(String bucketName)` _[[Javadoc]](http://minio.github.io/minio-java/io/minio/MinioClient.html#makeBucket-java.lang.String-)_
+### makeBucket(MakeBucketArgs args)
+`public void makeBucket(MakeBucketArgs args)` _[[Javadoc]](http://minio.github.io/minio-java/io/minio/MinioClient.html#makeBucket-io.minio.MakeBucketArgs-)_
 
-Creates a bucket with default region.
+Creates a bucket with given region and object lock feature enabled.
 
 __Parameters__
-| Parameter      | Type     | Description         |
-|:---------------|:---------|:--------------------|
-| ``bucketName`` | _String_ | Name of the bucket. |
-
-__Example__
-```java
-minioClient.makeBucket("my-bucketname");
-```
-
-<a name="makeBucket"></a>
-### makeBucket(String bucketName, String region)
-`public void makeBucket(String bucketName, String region)` _[[Javadoc]](http://minio.github.io/minio-java/io/minio/MinioClient.html#makeBucket-java.lang.String-java.lang.String-)_
-
-Creates a bucket with given region.
-
-__Parameters__
-| Parameter      | Type     | Description                                 |
-|:---------------|:---------|:--------------------------------------------|
-| ``bucketName`` | _String_ | Name of the bucket.                         |
-| ``region``     | _String_ | Region in which the bucket will be created. |
-
-__Example__
-```java
-minioClient.makeBucket("my-bucketname", "eu-west-1");
-```
-
-<a name="makeBucket"></a>
-### makeBucket(String bucketName, String region, boolean objectLock)
-`public void makeBucket(String bucketName, String region, boolean objectLock)` _[[Javadoc]](http://minio.github.io/minio-java/io/minio/MinioClient.html#makeBucket-java.lang.String-java.lang.String-boolean-)_
-
-Creates a bucket with object lock feature enabled.
-
-__Parameters__
-| Parameter      | Type      | Description                                            |
-|:---------------|:----------|:-------------------------------------------------------|
-| ``bucketName`` | _String_  | Name of the bucket.                                    |
-| ``region``     | _String_  | (Optional) Region in which the bucket will be created. |
-| ``objectLock`` | _boolean_ | Flag to enable object lock feature.                    |
+| Parameter      | Type             | Description                |
+|:---------------|:-----------------|:---------------------------|
+| ``args``       | _[MakeBucketArgs]_ | Arguments to create bucket |
 
 __Example__
 ```java
-minioClient.makeBucket("my-bucketname", "us-west-2", true);
+// Create bucket with default region.
+minioClient.makeBucket(new MakeBucketArgs.Builder().bucket("my-bucketname").build());
+// Create bucket with specific region.
+minioClient.makeBucket(
+    new MakeBucketArgs.Builder().bucket("my-bucketname").region("us-west-1").build());
+// Create object-lock enabled bucket with specific region.
+minioClient.makeBucket(
+    new MakeBucketArgs.Builder()
+        .bucket("my-bucketname")
+        .region("us-west-1")
+        .objectLock(true)
+        .build());
 ```
 
 <a name="removeAllBucketNotification"></a>

examples/EnableDisableObjectLegalHold.java

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import io.minio.MakeBucketArgs;
 import io.minio.MinioClient;
 import io.minio.PutObjectOptions;
 import io.minio.errors.ErrorResponseException;
@@ -55,7 +56,8 @@ public static void main(String[] args)
         System.out.println("my-bucketname already exists");
       } else {
         // Create bucket 'my-bucketname' with object lock functionality enabled
-        minioClient.makeBucket("my-bucketname", null, true);
+        minioClient.makeBucket(
+            new MakeBucketArgs.Builder().bucket("my-bucketname").objectLock(true).build());
         System.out.println(
             "my-bucketname is created successfully with object lock functionality enabled.");
       }