add arg builder to listenBucketNotification API

minio · May 22, 2020 · 9b6ef60 · 9b6ef60
1 parent 9fd2c92
commit 9b6ef60
Show file tree

Hide file tree

Showing 5 changed files with 175 additions and 31 deletions.
diff --git a/api/src/main/java/io/minio/ListenBucketNotificationArgs.java b/api/src/main/java/io/minio/ListenBucketNotificationArgs.java
@@ -0,0 +1,74 @@
+/*
+ * 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;
+
+import java.util.Arrays;
+
+/** Argument class of MinioClient.ListenBucketNotification(). */
+public class ListenBucketNotificationArgs extends BucketArgs {
+  private String prefix;
+  private String suffix;
+  private String[] events = null;
+
+  public String prefix() {
+    return prefix;
+  }
+
+  public String suffix() {
+    return suffix;
+  }
+
+  public String[] events() {
+    return Arrays.copyOf(events, events.length);
+  }
+
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  /** Argument builder of {@link ListenBucketNotificationArgs}. */
+  public static final class Builder
+      extends BucketArgs.Builder<Builder, ListenBucketNotificationArgs> {
+    private void validateEvents(String[] events) {
+      if (events == null) {
+        throw new IllegalArgumentException("null events");
+      }
+    }
+
+    protected void validate(ListenBucketNotificationArgs args) {
+      super.validate(args);
+      validateEvents(args.events);
+    }
+
+    public Builder prefix(String prefix) {
+      operations.add(args -> args.prefix = prefix);
+      return this;
+    }
+
+    public Builder suffix(String suffix) {
+      operations.add(args -> args.suffix = suffix);
+      return this;
+    }
+
+    public Builder events(String[] events) {
+      validateEvents(events);
+      final String[] eventsCopy = Arrays.copyOf(events, events.length);
+      operations.add(args -> args.events = eventsCopy);
+      return this;
+    }
+  }
+}
diff --git a/api/src/main/java/io/minio/MinioClient.java b/api/src/main/java/io/minio/MinioClient.java
@@ -5014,7 +5014,7 @@ public void removeIncompleteUpload(String bucketName, String objectName)
    * <pre>Example:{@code
    * String[] events = {"s3:ObjectCreated:*", "s3:ObjectAccessed:*"};
    * try (CloseableIterator<Result<NotificationInfo>> ci =
-   *     minioClient.listenBucketNotification("bcketName", "", "", events)) {
+   *     minioClient.listenBucketNotification("bucketName", "", "", events)) {
    *   while (ci.hasNext()) {
    *     NotificationRecords records = ci.next().get();
    *     for (Event event : records.events()) {
@@ -5044,19 +5044,79 @@ public void removeIncompleteUpload(String bucketName, String objectName)
    * @throws NoSuchAlgorithmException thrown to indicate missing of MD5 or SHA-256 digest library.
    * @throws XmlParserException thrown to indicate XML parsing error.
    */
+  @Deprecated
   public CloseableIterator<Result<NotificationRecords>> listenBucketNotification(
       String bucketName, String prefix, String suffix, String[] events)
       throws ErrorResponseException, IllegalArgumentException, InsufficientDataException,
           InternalException, InvalidBucketNameException, InvalidKeyException,
           InvalidResponseException, IOException, NoSuchAlgorithmException, XmlParserException {
+    return listenBucketNotification(
+        ListenBucketNotificationArgs.builder()
+            .bucket(bucketName)
+            .prefix(prefix)
+            .suffix(suffix)
+            .events(events)
+            .build());
+  }
+
+  /**
+   * Listens events of object prefix and suffix of a bucket. The returned closable iterator is
+   * lazily evaluated hence its required to iterate to get new records and must be used with
+   * try-with-resource to release underneath network resources.
+   *
+   * <pre>Example:{@code
+   * String[] events = {"s3:ObjectCreated:*", "s3:ObjectAccessed:*"};
+   * try (CloseableIterator<Result<NotificationRecords>> ci =
+   *     minioClient.listenBucketNotification(
+   *         ListenBucketNotificationArgs.builder()
+   *             .bucket("bucketName")
+   *             .prefix("")
+   *             .suffix("")
+   *             .events(events)
+   *             .build())) {
+   *   while (ci.hasNext()) {
+   *     NotificationRecords records = ci.next().get();
+   *     for (Event event : records.events()) {
+   *       System.out.println("Event " + event.eventType() + " occurred at "
+   *           + event.eventTime() + " for " + event.bucketName() + "/"
+   *           + event.objectName());
+   *     }
+   *   }
+   * }
+   * }</pre>
+   *
+   * @param args {@link ListenBucketNotificationArgs} object.
+   * @return CloseableIterator&ltResult&ltNotificationRecords&gt&gt - Lazy closable iterator
+   *     contains event records.
+   * @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 XmlParserException thrown to indicate XML parsing error.
+   */
+  public CloseableIterator<Result<NotificationRecords>> listenBucketNotification(
+      ListenBucketNotificationArgs args)
+      throws ErrorResponseException, IllegalArgumentException, InsufficientDataException,
+          InternalException, InvalidBucketNameException, InvalidKeyException,
+          InvalidResponseException, IOException, NoSuchAlgorithmException, XmlParserException {
+    if (args == null) {
+      throw new IllegalArgumentException("null arguments");
+    }
+
     Multimap<String, String> queryParamMap = HashMultimap.create();
-    queryParamMap.put("prefix", prefix);
-    queryParamMap.put("suffix", suffix);
-    for (String event : events) {
+    queryParamMap.put("prefix", args.prefix());
+    queryParamMap.put("suffix", args.suffix());
+    for (String event : args.events()) {
       queryParamMap.put("events", event);
     }
 
-    Response response = executeGet(bucketName, "", queryParamMap);
+    Response response = executeGet(args.bucket(), "", queryParamMap);
 
     NotificationResultRecords result = new NotificationResultRecords(response);
     return result.closeableIterator();

diff --git a/docs/API.md b/docs/API.md
@@ -437,18 +437,15 @@ for (Bucket bucket : bucketList) {
 ```
 
 <a name="listenBucketNotification"></a>
-### listenBucketNotification(String bucketName, String prefix, String suffix, String[] events)
-`public CloseableIterator<Result<NotificationRecords>> listenBucketNotification(String bucketName, String prefix, String suffix, String[] events)` _[[Javadoc]](http://minio.github.io/minio-java/io/minio/MinioClient.html#listenBucketNotification-java.lang.String-java.lang.String-java.lang.String-java.lang.String:A-)_
+### listenBucketNotification(ListenBucketNotificationArgs args)
+`public CloseableIterator<Result<NotificationRecords>> listenBucketNotification(ListenBucketNotificationArgs args)` _[[Javadoc]](http://minio.github.io/minio-java/io/minio/MinioClient.html#listenBucketNotification-io.minio.ListenBucketNotificationArgs-)_
 
 Listens events of object prefix and suffix of a bucket. The returned closable iterator is lazily evaluated hence its required to iterate to get new records and must be used with try-with-resource to release underneath network resources.
 
 __Parameters__
-| Parameter      | Type       | Description                                 |
-|:---------------|:-----------|:--------------------------------------------|
-| ``bucketName`` | _String_   | Name of the bucket.                         |
-| ``prefix``     | _String_   | Listen events of object starts with prefix. |
-| ``suffix``     | _String_   | Listen events of object ends with suffix.   |
-| ``events``     | _String[]_ | Events to listen.                           |
+| Parameter | Type                             | Description |
+|:----------|:---------------------------------|:------------|
+| ``args``  | _[ListenBucketNotificationArgs]_ | Arguments.  |
 
 | Returns                                                                                                 |
 |:--------------------------------------------------------------------------------------------------------|
@@ -457,8 +454,14 @@ __Parameters__
 __Example__
 ```java
 String[] events = {"s3:ObjectCreated:*", "s3:ObjectAccessed:*"};
-try (CloseableIterator<Result<NotificationInfo>> ci =
-    minioClient.listenBucketNotification("bcketName", "", "", events)) {
+try (CloseableIterator<Result<NotificationRecords>> ci =
+    minioClient.listenBucketNotification(
+        ListenBucketNotificationArgs.builder()
+            .bucket("bucketName")
+            .prefix("")
+            .suffix("")
+            .events(events)
+            .build())) {
   while (ci.hasNext()) {
     NotificationRecords records = ci.next().get();
     for (Event event : records.events()) {
@@ -1564,3 +1567,4 @@ ObjectStat objectStat =
 [Method]: http://minio.github.io/minio-java/io/minio/http/Method.html
 [StatObjectArgs]: http://minio.github.io/minio-java/io/minio/StatObjectArgs.html
 [RemoveObjectArgs]: http://minio.github.io/minio-java/io/minio/RemoveObjectArgs.html
+[ListenBucketNotificationArgs]: http://minio.github.io/minio-java/io/minio/ListenBucketNotificationArgs.html
diff --git a/examples/ListenBucketNotification.java b/examples/ListenBucketNotification.java
@@ -15,6 +15,7 @@
  */
 
 import io.minio.CloseableIterator;
+import io.minio.ListenBucketNotificationArgs;
 import io.minio.MinioClient;
 import io.minio.Result;
 import io.minio.errors.MinioException;
@@ -38,7 +39,13 @@ public static void main(String[] args)
 
       String[] events = {"s3:ObjectCreated:*", "s3:ObjectAccessed:*"};
       try (CloseableIterator<Result<NotificationRecords>> ci =
-          minioClient.listenBucketNotification("bcketName", "", "", events)) {
+          minioClient.listenBucketNotification(
+              ListenBucketNotificationArgs.builder()
+                  .bucket("bucketName")
+                  .prefix("")
+                  .suffix("")
+                  .events(events)
+                  .build())) {
         while (ci.hasNext()) {
           NotificationRecords records = ci.next().get();
           Event event = records.events().get(0);

diff --git a/functional/FunctionalTest.java b/functional/FunctionalTest.java
@@ -26,6 +26,7 @@
 import io.minio.EnableVersioningArgs;
 import io.minio.ErrorCode;
 import io.minio.ListObjectsArgs;
+import io.minio.ListenBucketNotificationArgs;
 import io.minio.MakeBucketArgs;
 import io.minio.MinioClient;
 import io.minio.ObjectStat;
@@ -4093,12 +4094,10 @@ public static void removeAllBucketNotification_test1() throws Exception {
     }
   }
 
-  /** Test: listenBucketNotification(String bucketName). */
+  /** Test: listenBucketNotification(ListenBucketNotificationArgs args). */
   public static void listenBucketNotification_test1() throws Exception {
     if (!mintEnv) {
-      System.out.println(
-          "Test: listenBucketNotification(String bucketName, String prefix, "
-              + "String suffix, String[] events)");
+      System.out.println("Test: listenBucketNotification(ListenBucketNotificationArgs args)");
     }
 
     long startTime = System.currentTimeMillis();
@@ -4109,7 +4108,14 @@ public static void listenBucketNotification_test1() throws Exception {
       client.makeBucket(MakeBucketArgs.builder().bucket(bucketName).region(region).build());
 
       String[] events = {"s3:ObjectCreated:*", "s3:ObjectAccessed:*"};
-      ci = client.listenBucketNotification(bucketName, "prefix", "suffix", events);
+      ci =
+          client.listenBucketNotification(
+              ListenBucketNotificationArgs.builder()
+                  .bucket(bucketName)
+                  .prefix("prefix")
+                  .suffix("suffix")
+                  .events(events)
+                  .build());
 
       client.putObject(bucketName, "prefix-random-suffix", file, new PutObjectOptions(1 * KB, -1));
 
@@ -4133,27 +4139,20 @@ public static void listenBucketNotification_test1() throws Exception {
       }
 
       mintSuccessLog(
-          "listenBucketNotification(String bucketName, String prefix, "
-              + "String suffix, String[] events)",
-          null,
-          startTime);
+          "listenBucketNotification(ListenBucketNotificationArgs args)", null, startTime);
     } catch (Exception e) {
       if (e instanceof ErrorResponseException) {
         ErrorResponseException exp = (ErrorResponseException) e;
         ErrorResponse errorResponse = exp.errorResponse();
         if (errorResponse != null && errorResponse.errorCode() == ErrorCode.NOT_IMPLEMENTED) {
           mintIgnoredLog(
-              "listenBucketNotification(String bucketName, String prefix, "
-                  + "String suffix, String[] events)",
-              null,
-              startTime);
+              "listenBucketNotification(ListenBucketNotificationArgs args)", null, startTime);
           return;
         }
       }
 
       mintFailedLog(
-          "listenBucketNotification(String bucketName, String prefix, "
-              + "String suffix, String[] events)",
+          "listenBucketNotification(ListenBucketNotificationArgs args)",
           null,
           startTime,
           null,