feat: Support chunk upload session plan API (box/box-openapi#616) (#1979)

Author: box-sdk-build

.codegen.json

@@ -1 +1 @@
-{ "engineHash": "04310d4", "specHash": "be75fa1", "version": "10.16.2" }
+{ "engineHash": "04310d4", "specHash": "88cd5aa", "version": "10.16.2" }

docs/chunkeduploads.md

@@ -12,6 +12,8 @@ This is a manager for chunked uploads (allowed for files at least 20MB).
 - [Remove upload session](#remove-upload-session)
 - [List parts by URL](#list-parts-by-url)
 - [List parts](#list-parts)
+- [Plan upload session by URL](#plan-upload-session-by-url)
+- [Plan upload session](#plan-upload-session)
 - [Commit upload session by URL](#commit-upload-session-by-url)
 - [Commit upload session](#commit-upload-session)
 - [Upload big file](#upload-big-file)
@@ -341,6 +343,74 @@ This function returns a value of type `UploadParts`.
 Returns a list of parts that have been uploaded.
 
 
+## Plan upload session by URL
+
+Plan an upload session by checking which parts already exist on the server.
+This endpoint allows clients to optimize uploads by skipping parts that
+have already been uploaded (cache hits) and only uploading missing parts.
+
+The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)
+and [`Get upload session`](e://get-files-upload-sessions-id) endpoints.
+
+This operation is performed by calling function `createFileUploadSessionPlanByUrl`.
+
+See the endpoint docs at
+[API Reference](https://developer.box.com/reference/post-files-upload-sessions-id-plan/).
+
+*Currently we don't have an example for calling `createFileUploadSessionPlanByUrl` in integration tests*
+
+### Arguments
+
+- url `String`
+  - URL of createFileUploadSessionPlan method
+- requestBody `UploadSessionPlanRequest`
+  - Request body of createFileUploadSessionPlan method
+- headers `CreateFileUploadSessionPlanByUrlHeaders`
+  - Headers of createFileUploadSessionPlan method
+
+
+### Returns
+
+This function returns a value of type `UploadSessionPlanResponse`.
+
+Returns information about which parts already exist (hits)
+and which parts need to be uploaded (misses).
+
+
+## Plan upload session
+
+Plan an upload session by checking which parts already exist on the server.
+This endpoint allows clients to optimize uploads by skipping parts that
+have already been uploaded (cache hits) and only uploading missing parts.
+
+The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)
+and [`Get upload session`](e://get-files-upload-sessions-id) endpoints.
+
+This operation is performed by calling function `createFileUploadSessionPlan`.
+
+See the endpoint docs at
+[API Reference](https://developer.box.com/reference/post-files-upload-sessions-id-plan/).
+
+*Currently we don't have an example for calling `createFileUploadSessionPlan` in integration tests*
+
+### Arguments
+
+- uploadSessionId `String`
+  - The ID of the upload session. Example: "D5E3F7A"
+- requestBody `UploadSessionPlanRequest`
+  - Request body of createFileUploadSessionPlan method
+- headers `CreateFileUploadSessionPlanHeaders`
+  - Headers of createFileUploadSessionPlan method
+
+
+### Returns
+
+This function returns a value of type `UploadSessionPlanResponse`.
+
+Returns information about which parts already exist (hits)
+and which parts need to be uploaded (misses).
+
+
 ## Commit upload session by URL
 
 Close an upload session and create a file from the uploaded chunks.

src/main/java/com/box/sdkgen/managers/chunkeduploads/ChunkedUploadsManager.java

@@ -25,6 +25,8 @@
 import com.box.sdkgen.schemas.uploadpart.UploadPart;
 import com.box.sdkgen.schemas.uploadparts.UploadParts;
 import com.box.sdkgen.schemas.uploadsession.UploadSession;
+import com.box.sdkgen.schemas.uploadsessionplanrequest.UploadSessionPlanRequest;
+import com.box.sdkgen.schemas.uploadsessionplanresponse.UploadSessionPlanResponse;
 import com.box.sdkgen.serialization.json.JsonManager;
 import java.io.InputStream;
 import java.util.Arrays;
@@ -586,6 +588,121 @@ public UploadParts getFileUploadSessionParts(
     return JsonManager.deserialize(response.getData(), UploadParts.class);
   }
 
+  /**
+   * Using this method with urls provided in response when creating a new upload session is
+   * preferred to use over CreateFileUploadSessionPlan method. This allows to always upload your
+   * content to the closest Box data center and can significantly improve upload speed. Plan an
+   * upload session by checking which parts already exist on the server. This endpoint allows
+   * clients to optimize uploads by skipping parts that have already been uploaded (cache hits) and
+   * only uploading missing parts.
+   *
+   * <p>The actual endpoint URL is returned by the [`Create upload
+   * session`](e://post-files-upload-sessions) and [`Get upload
+   * session`](e://get-files-upload-sessions-id) endpoints.
+   *
+   * @param url URL of createFileUploadSessionPlan method
+   * @param requestBody Request body of createFileUploadSessionPlan method
+   */
+  public UploadSessionPlanResponse createFileUploadSessionPlanByUrl(
+      String url, UploadSessionPlanRequest requestBody) {
+    return createFileUploadSessionPlanByUrl(
+        url, requestBody, new CreateFileUploadSessionPlanByUrlHeaders());
+  }
+
+  /**
+   * Using this method with urls provided in response when creating a new upload session is
+   * preferred to use over CreateFileUploadSessionPlan method. This allows to always upload your
+   * content to the closest Box data center and can significantly improve upload speed. Plan an
+   * upload session by checking which parts already exist on the server. This endpoint allows
+   * clients to optimize uploads by skipping parts that have already been uploaded (cache hits) and
+   * only uploading missing parts.
+   *
+   * <p>The actual endpoint URL is returned by the [`Create upload
+   * session`](e://post-files-upload-sessions) and [`Get upload
+   * session`](e://get-files-upload-sessions-id) endpoints.
+   *
+   * @param url URL of createFileUploadSessionPlan method
+   * @param requestBody Request body of createFileUploadSessionPlan method
+   * @param headers Headers of createFileUploadSessionPlan method
+   */
+  public UploadSessionPlanResponse createFileUploadSessionPlanByUrl(
+      String url,
+      UploadSessionPlanRequest requestBody,
+      CreateFileUploadSessionPlanByUrlHeaders headers) {
+    Map<String, String> headersMap = prepareParams(mergeMaps(mapOf(), headers.getExtraHeaders()));
+    FetchResponse response =
+        this.networkSession
+            .getNetworkClient()
+            .fetch(
+                new FetchOptions.Builder(url, "POST")
+                    .headers(headersMap)
+                    .data(JsonManager.serialize(requestBody))
+                    .contentType("application/json")
+                    .responseFormat(ResponseFormat.JSON)
+                    .auth(this.auth)
+                    .networkSession(this.networkSession)
+                    .build());
+    return JsonManager.deserialize(response.getData(), UploadSessionPlanResponse.class);
+  }
+
+  /**
+   * Plan an upload session by checking which parts already exist on the server. This endpoint
+   * allows clients to optimize uploads by skipping parts that have already been uploaded (cache
+   * hits) and only uploading missing parts.
+   *
+   * <p>The actual endpoint URL is returned by the [`Create upload
+   * session`](e://post-files-upload-sessions) and [`Get upload
+   * session`](e://get-files-upload-sessions-id) endpoints.
+   *
+   * @param uploadSessionId The ID of the upload session. Example: "D5E3F7A"
+   * @param requestBody Request body of createFileUploadSessionPlan method
+   */
+  public UploadSessionPlanResponse createFileUploadSessionPlan(
+      String uploadSessionId, UploadSessionPlanRequest requestBody) {
+    return createFileUploadSessionPlan(
+        uploadSessionId, requestBody, new CreateFileUploadSessionPlanHeaders());
+  }
+
+  /**
+   * Plan an upload session by checking which parts already exist on the server. This endpoint
+   * allows clients to optimize uploads by skipping parts that have already been uploaded (cache
+   * hits) and only uploading missing parts.
+   *
+   * <p>The actual endpoint URL is returned by the [`Create upload
+   * session`](e://post-files-upload-sessions) and [`Get upload
+   * session`](e://get-files-upload-sessions-id) endpoints.
+   *
+   * @param uploadSessionId The ID of the upload session. Example: "D5E3F7A"
+   * @param requestBody Request body of createFileUploadSessionPlan method
+   * @param headers Headers of createFileUploadSessionPlan method
+   */
+  public UploadSessionPlanResponse createFileUploadSessionPlan(
+      String uploadSessionId,
+      UploadSessionPlanRequest requestBody,
+      CreateFileUploadSessionPlanHeaders headers) {
+    Map<String, String> headersMap = prepareParams(mergeMaps(mapOf(), headers.getExtraHeaders()));
+    FetchResponse response =
+        this.networkSession
+            .getNetworkClient()
+            .fetch(
+                new FetchOptions.Builder(
+                        String.join(
+                            "",
+                            this.networkSession.getBaseUrls().getUploadUrl(),
+                            "/2.0/files/upload_sessions/",
+                            convertToString(uploadSessionId),
+                            "/plan"),
+                        "POST")
+                    .headers(headersMap)
+                    .data(JsonManager.serialize(requestBody))
+                    .contentType("application/json")
+                    .responseFormat(ResponseFormat.JSON)
+                    .auth(this.auth)
+                    .networkSession(this.networkSession)
+                    .build());
+    return JsonManager.deserialize(response.getData(), UploadSessionPlanResponse.class);
+  }
+
   /**
    * Using this method with urls provided in response when creating a new upload session is
    * preferred to use over CreateFileUploadSessionCommit method. This allows to always upload your

src/main/java/com/box/sdkgen/managers/chunkeduploads/CreateFileUploadSessionPlanByUrlHeaders.java

@@ -0,0 +1,42 @@
+package com.box.sdkgen.managers.chunkeduploads;
+
+import static com.box.sdkgen.internal.utils.UtilsManager.mapOf;
+
+import java.util.Map;
+
+public class CreateFileUploadSessionPlanByUrlHeaders {
+
+  /** Extra headers that will be included in the HTTP request. */
+  public Map<String, String> extraHeaders;
+
+  public CreateFileUploadSessionPlanByUrlHeaders() {
+    this.extraHeaders = mapOf();
+  }
+
+  protected CreateFileUploadSessionPlanByUrlHeaders(Builder builder) {
+    this.extraHeaders = builder.extraHeaders;
+  }
+
+  public Map<String, String> getExtraHeaders() {
+    return extraHeaders;
+  }
+
+  public static class Builder {
+
+    protected Map<String, String> extraHeaders;
+
+    public Builder() {}
+
+    public Builder extraHeaders(Map<String, String> extraHeaders) {
+      this.extraHeaders = extraHeaders;
+      return this;
+    }
+
+    public CreateFileUploadSessionPlanByUrlHeaders build() {
+      if (this.extraHeaders == null) {
+        this.extraHeaders = mapOf();
+      }
+      return new CreateFileUploadSessionPlanByUrlHeaders(this);
+    }
+  }
+}

src/main/java/com/box/sdkgen/managers/chunkeduploads/CreateFileUploadSessionPlanHeaders.java

@@ -0,0 +1,42 @@
+package com.box.sdkgen.managers.chunkeduploads;
+
+import static com.box.sdkgen.internal.utils.UtilsManager.mapOf;
+
+import java.util.Map;
+
+public class CreateFileUploadSessionPlanHeaders {
+
+  /** Extra headers that will be included in the HTTP request. */
+  public Map<String, String> extraHeaders;
+
+  public CreateFileUploadSessionPlanHeaders() {
+    this.extraHeaders = mapOf();
+  }
+
+  protected CreateFileUploadSessionPlanHeaders(Builder builder) {
+    this.extraHeaders = builder.extraHeaders;
+  }
+
+  public Map<String, String> getExtraHeaders() {
+    return extraHeaders;
+  }
+
+  public static class Builder {
+
+    protected Map<String, String> extraHeaders;
+
+    public Builder() {}
+
+    public Builder extraHeaders(Map<String, String> extraHeaders) {
+      this.extraHeaders = extraHeaders;
+      return this;
+    }
+
+    public CreateFileUploadSessionPlanHeaders build() {
+      if (this.extraHeaders == null) {
+        this.extraHeaders = mapOf();
+      }
+      return new CreateFileUploadSessionPlanHeaders(this);
+    }
+  }
+}

src/main/java/com/box/sdkgen/schemas/uploadpartplan/UploadPartPlan.java

@@ -0,0 +1,81 @@
+package com.box.sdkgen.schemas.uploadpartplan;
+
+import com.box.sdkgen.internal.SerializableObject;
+import com.fasterxml.jackson.annotation.JsonFilter;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.Objects;
+
+/** Represents a planned upload part with `SHA-512` hash for upload session planning. */
+@JsonFilter("nullablePropertyFilter")
+public class UploadPartPlan extends SerializableObject {
+
+  /**
+   * The offset of the chunk within the file in bytes. The lower bound of the position of the chunk
+   * within the file.
+   */
+  protected final long offset;
+
+  /** The size of the chunk in bytes. */
+  protected final long size;
+
+  /** The `SHA-512` hash of the chunk. */
+  protected final String sha512;
+
+  public UploadPartPlan(
+      @JsonProperty("offset") long offset,
+      @JsonProperty("size") long size,
+      @JsonProperty("sha512") String sha512) {
+    super();
+    this.offset = offset;
+    this.size = size;
+    this.sha512 = sha512;
+  }
+
+  public long getOffset() {
+    return offset;
+  }
+
+  public long getSize() {
+    return size;
+  }
+
+  public String getSha512() {
+    return sha512;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (o == null || getClass() != o.getClass()) {
+      return false;
+    }
+    UploadPartPlan casted = (UploadPartPlan) o;
+    return Objects.equals(offset, casted.offset)
+        && Objects.equals(size, casted.size)
+        && Objects.equals(sha512, casted.sha512);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(offset, size, sha512);
+  }
+
+  @Override
+  public String toString() {
+    return "UploadPartPlan{"
+        + "offset='"
+        + offset
+        + '\''
+        + ", "
+        + "size='"
+        + size
+        + '\''
+        + ", "
+        + "sha512='"
+        + sha512
+        + '\''
+        + "}";
+  }
+}