Add restoreObject API support (#1227)

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

.github/workflows/gradle.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Check limited Guava usage
         if: matrix.os == 'ubuntu-latest'
         run: |
-          if grep -I -r --exclude-dir=.github "com.google.common.base.Objects" . ; then
+          if grep --with-filename --line-number --no-messages --recursive --exclude-dir=.github "com.google.common.base.Objects" .; then
             echo "Error: use java.util.Objects instead of com.google.common.base.Objects"
             exit 1
           fi

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

@@ -1215,6 +1215,45 @@ public void remove() {
     };
   }
 
+  /**
+   * Restores an object asynchronously.
+   *
+   * <pre>Example:{@code
+   * // Restore object.
+   * CompletableFuture<Void> future = minioAsyncClient.restoreObject(
+   *     RestoreObjectArgs.builder()
+   *         .bucket("my-bucketname")
+   *         .object("my-objectname")
+   *         .request(new RestoreRequest(null, null, null, null, null, null))
+   *         .build());
+   *
+   * // Restore versioned object.
+   * CompletableFuture<Void> future = minioAsyncClient.restoreObject(
+   *     RestoreObjectArgs.builder()
+   *         .bucket("my-bucketname")
+   *         .object("my-versioned-objectname")
+   *         .versionId("my-versionid")
+   *         .request(new RestoreRequest(null, null, null, null, null, null))
+   *         .build());
+   * }</pre>
+   *
+   * @param args {@link RestoreObjectArgs} object.
+   * @return {@link CompletableFuture}&lt;{@link Void}&gt; object.
+   * @throws InsufficientDataException thrown to indicate not enough data available in InputStream.
+   * @throws InternalException thrown to indicate internal library error.
+   * @throws InvalidKeyException thrown to indicate missing of HMAC SHA-256 library.
+   * @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 CompletableFuture<Void> restoreObject(RestoreObjectArgs args)
+      throws InsufficientDataException, InternalException, InvalidKeyException, IOException,
+          NoSuchAlgorithmException, XmlParserException {
+    checkArgs(args);
+    return executePostAsync(args, null, newMultimap("restore", ""), args.request())
+        .thenAccept(response -> response.close());
+  }
+
   /**
    * Lists objects information optionally with versions of a bucket. Supports both the versions 1
    * and 2 of the S3 API. By default, the <a

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

@@ -656,6 +656,52 @@ public Iterable<Result<DeleteError>> removeObjects(RemoveObjectsArgs args) {
     return asyncClient.removeObjects(args);
   }
 
+  /**
+   * Restores an object.
+   *
+   * <pre>Example:{@code
+   * // Restore object.
+   * minioClient.restoreObject(
+   *     RestoreObjectArgs.builder()
+   *         .bucket("my-bucketname")
+   *         .object("my-objectname")
+   *         .request(new RestoreRequest(null, null, null, null, null, null))
+   *         .build());
+   *
+   * // Restore versioned object.
+   * minioClient.restoreObject(
+   *     RestoreObjectArgs.builder()
+   *         .bucket("my-bucketname")
+   *         .object("my-versioned-objectname")
+   *         .versionId("my-versionid")
+   *         .request(new RestoreRequest(null, null, null, null, null, null))
+   *         .build());
+   * }</pre>
+   *
+   * @param args {@link RestoreObjectArgs} object.
+   * @throws ErrorResponseException thrown to indicate S3 service returned an error response.
+   * @throws InsufficientDataException thrown to indicate not enough data available in InputStream.
+   * @throws InternalException thrown to indicate internal library error.
+   * @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 void restoreObject(RestoreObjectArgs args)
+      throws ErrorResponseException, InsufficientDataException, InternalException,
+          InvalidKeyException, InvalidResponseException, IOException, NoSuchAlgorithmException,
+          ServerException, XmlParserException {
+    try {
+      asyncClient.restoreObject(args).get();
+    } catch (InterruptedException e) {
+      throw new RuntimeException(e);
+    } catch (ExecutionException e) {
+      asyncClient.throwEncapsulatedException(e);
+    }
+  }
+
   /**
    * Lists objects information optionally with versions of a bucket. Supports both the versions 1
    * and 2 of the S3 API. By default, the <a

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

@@ -0,0 +1,66 @@
+/*
+ * MinIO Java SDK for Amazon S3 Compatible Cloud Storage, (C) 2022 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 io.minio.messages.RestoreRequest;
+import java.util.Objects;
+
+/** Argument class of {@link MinioClient#restoreObject}. */
+public class RestoreObjectArgs extends ObjectVersionArgs {
+  private RestoreRequest request;
+
+  public RestoreRequest request() {
+    return request;
+  }
+
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  /** Argument builder of {@link RestoreObjectArgs}. */
+  public static final class Builder extends ObjectVersionArgs.Builder<Builder, RestoreObjectArgs> {
+    private void validateRequest(RestoreRequest request) {
+      validateNotNull(request, "request");
+    }
+
+    public Builder request(RestoreRequest request) {
+      validateRequest(request);
+      operations.add(args -> args.request = request);
+      return this;
+    }
+
+    @Override
+    protected void validate(RestoreObjectArgs args) {
+      super.validate(args);
+      validateRequest(args.request());
+    }
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (!(o instanceof RestoreObjectArgs)) return false;
+    if (!super.equals(o)) return false;
+    RestoreObjectArgs that = (RestoreObjectArgs) o;
+    return Objects.equals(request, that.request);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(super.hashCode(), request);
+  }
+}

api/src/main/java/io/minio/messages/AccessControlList.java

@@ -0,0 +1,40 @@
+/*
+ * MinIO Java SDK for Amazon S3 Compatible Cloud Storage, (C) 2021 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.messages;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+import javax.annotation.Nonnull;
+import org.simpleframework.xml.ElementList;
+import org.simpleframework.xml.Root;
+
+/** Helper class to denote access control list of {@link S3OutputLocation}. */
+@Root(name = "AccessControlList")
+@edu.umd.cs.findbugs.annotations.SuppressFBWarnings(value = "URF_UNREAD_FIELD")
+public class AccessControlList {
+  @ElementList(name = "Grant", inline = true)
+  private List<Grant> grants;
+
+  public AccessControlList(@Nonnull List<Grant> grants) {
+    Objects.requireNonNull(grants, "Grants must not be null");
+    if (grants.size() == 0) {
+      throw new IllegalArgumentException("Grants must not be empty");
+    }
+    this.grants = Collections.unmodifiableList(grants);
+  }
+}

api/src/main/java/io/minio/messages/CannedAcl.java

@@ -0,0 +1,72 @@
+/*
+ * MinIO Java SDK for Amazon S3 Compatible Cloud Storage, (C) 2021 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.messages;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import org.simpleframework.xml.Root;
+import org.simpleframework.xml.convert.Convert;
+import org.simpleframework.xml.convert.Converter;
+import org.simpleframework.xml.stream.InputNode;
+import org.simpleframework.xml.stream.OutputNode;
+
+/** CannedAcl representing retrieval cannedAcl value. */
+@Root(name = "CannedAcl")
+@Convert(CannedAcl.CannedAclConverter.class)
+public enum CannedAcl {
+  PRIVATE("private"),
+  PUBLIC_READ("public-read"),
+  PUBLIC_READ_WRITE("public-read-write"),
+  AUTHENTICATED_READ("authenticated-read"),
+  AWS_EXEC_READ("aws-exec-read"),
+  BUCKET_OWNER_READ("bucket-owner-read"),
+  BUCKET_OWNER_FULL_CONTROL("bucket-owner-full-control");
+
+  private final String value;
+
+  private CannedAcl(String value) {
+    this.value = value;
+  }
+
+  public String toString() {
+    return this.value;
+  }
+
+  /** Returns CannedAcl of given string. */
+  @JsonCreator
+  public static CannedAcl fromString(String cannedAclString) {
+    for (CannedAcl cannedAcl : CannedAcl.values()) {
+      if (cannedAclString.equals(cannedAcl.value)) {
+        return cannedAcl;
+      }
+    }
+
+    throw new IllegalArgumentException("Unknown canned ACL '" + cannedAclString + "'");
+  }
+
+  /** XML converter class. */
+  public static class CannedAclConverter implements Converter<CannedAcl> {
+    @Override
+    public CannedAcl read(InputNode node) throws Exception {
+      return CannedAcl.fromString(node.getValue());
+    }
+
+    @Override
+    public void write(OutputNode node, CannedAcl cannedAcl) throws Exception {
+      node.setValue(cannedAcl.toString());
+    }
+  }
+}

api/src/main/java/io/minio/messages/Encryption.java

@@ -0,0 +1,47 @@
+/*
+ * MinIO Java SDK for Amazon S3 Compatible Cloud Storage, (C) 2021 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.messages;
+
+import java.util.Objects;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import org.simpleframework.xml.Element;
+import org.simpleframework.xml.Root;
+
+/** Helper class to denote encryption information of {@link S3OutputLocation}. */
+@Root(name = "Encryption")
+@edu.umd.cs.findbugs.annotations.SuppressFBWarnings(value = "URF_UNREAD_FIELD")
+public class Encryption {
+  @Element(name = "EncryptionType")
+  private SseAlgorithm encryptionType;
+
+  @Element(name = "KMSContext", required = false)
+  private String kmsContext;
+
+  @Element(name = "KMSKeyId", required = false)
+  private String kmsKeyId;
+
+  public Encryption(
+      @Nonnull SseAlgorithm encryptionType,
+      @Nullable String kmsContext,
+      @Nullable String kmsKeyId) {
+    this.encryptionType =
+        Objects.requireNonNull(encryptionType, "Encryption type must not be null");
+    this.kmsContext = kmsContext;
+    this.kmsKeyId = kmsKeyId;
+  }
+}

api/src/main/java/io/minio/messages/GlacierJobParameters.java

@@ -0,0 +1,34 @@
+/*
+ * MinIO Java SDK for Amazon S3 Compatible Cloud Storage, (C) 2021 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.messages;
+
+import java.util.Objects;
+import javax.annotation.Nonnull;
+import org.simpleframework.xml.Element;
+import org.simpleframework.xml.Root;
+
+/** Helper class to denote S3 Glacier job parameters of {@link RestoreRequest}. */
+@Root(name = "GlacierJobParameters")
+@edu.umd.cs.findbugs.annotations.SuppressFBWarnings(value = "URF_UNREAD_FIELD")
+public class GlacierJobParameters {
+  @Element(name = "Tier")
+  private Tier tier;
+
+  public GlacierJobParameters(@Nonnull Tier tier) {
+    this.tier = Objects.requireNonNull(tier, "Tier must not be null");
+  }
+}