Add new API for get files and file versions under retention for assignment

CHANGELOG.md

@@ -9,6 +9,7 @@ __New Features and Enhancements:__
 - Add support for `is_external_collab_restricted` parameter for User ([#896](https://github.com/box/box-java-sdk/pull/896))
 - Add configurable permissions support for `GroupMembership` ([#875](https://github.com/box/box-java-sdk/pull/875))
 - Add `SHIELD_JUSTIFICATION_APPROVAL` event type ([#898](https://github.com/box/box-java-sdk/pull/898))
+- Add ability to get files under retention for assignment and file versions under retention for assignment ([#899](https://github.com/box/box-java-sdk/pull/899))
 
 __Bug Fixes:__
 

doc/retention_policies.md

@@ -15,7 +15,9 @@ A retention policy blocks permanent deletion of content for a specified amount o
 - [Create Retention Policy Assignment](#create-retention-policy-assignment)
 - [Get Retention Policy Assignment](#get-retention-policy-assignment)
 - [Get File Version Retention](#get-file-version-retention)
-- [Get File Version Retentions](#get-file-version-retentions)
+- [Get File Version Retentions](#get-file-version-retentions) (will be deprecated in the future, use [Get Files Under Retention For Assignment](#get-files-under-retention-for-assignment) and [Get File Version Under Retention For Assignment](#get-file-versions-under-retention-for-assignment) instead)
+- [Get Files Under Retention For Assignment](#get-files-under-retention-for-assignment)
+- [Get File Version Under Retention For Assignment](#get-file-versions-under-retention-for-assignment)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -236,3 +238,41 @@ for (BoxFileVersionRetention.Info retentionInfo : retentions) {
 [get-all-file-version-retentions]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersionRetention.html#getAll-com.box.sdk.BoxAPIConnection-java.lang.String...-
 [query-filter]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersionRetention.QueryFilter.html
 [get-all-file-version-retentions-with-filter]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersionRetention.html#getRetentions-com.box.sdk.BoxAPIConnection-com.box.sdk.BoxFileVersionRetention.QueryFilter-java.lang.String...-
+
+Get Files Under Retention For Assignment
+----------------------------------------
+
+To get an iterable with all files under retention for assignment
+policy, call the [`getFilesUnderRetention(BoxAPIConnection api, int limit, String... fields)`][get-files-under-retention-for-assignment]
+method. This will return an interable with [`BoxFile.Info`][file] objects containing information about the files.
+
+<!-- sample get_files_under_retention_for_assignment -->
+```java
+BoxRetentionPolicyAssignment policyAssignment = new BoxRetentionPolicyAssignment(api, id);
+Iterable<BoxFile.Info> filesUnderRetention = policyAssignment.getFilesUnderRetention();
+for (BoxFile.Info item : filesUnderRetention){
+    // Do something with the files under retention.
+}
+```
+
+[get-files-under-retention-for-assignment]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicyAssignment.html#getFilesUnderRetention-com.box.sdk.BoxAPIConnection-java.lang.String...-
+[file]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.Info.html
+
+Get File Versions Under Retention For Assignment
+------------------------------------------------
+
+To get an iterable with all file versions under retention for assignment
+policy, call the [`getFileVersionsUnderRetention(BoxAPIConnection api, int limit, String... fields)`][get-file-versions-under-retention-for-assignment]
+method. This will return an interable with [`BoxFileVersion`][file-version] objects containing information about the file versions.
+
+<!-- sample get_file_versions_under_retention_for_assignment -->
+```java
+BoxRetentionPolicyAssignment policyAssignment = new BoxRetentionPolicyAssignment(api, id);
+Iterable<BoxFileVersion> fileVersionsUnderRetention = policyAssignment.getFileVersionsUnderRetention();
+for (BoxFileVersion fileVersion : fileVersionsUnderRetention){
+	// Do something with the file versions under retention.
+}
+```
+
+[get-file-versions-under-retention-for-assignment]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicyAssignment.html#getFileVersionsUnderRetention-com.box.sdk.BoxAPIConnection-java.lang.String...-
+[file-version]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersion.html

src/main/java/com/box/sdk/BoxFileVersion.java

@@ -40,6 +40,7 @@ public class BoxFileVersion extends BoxResource {
     private Date restoredAt;
     private BoxUser.Info restoredBy;
     private Date purgedAt;
+    private BoxFileVersion fileVersion;
 
     /**
      * Constructs a BoxFileVersion from a JSON string.
@@ -106,6 +107,10 @@ private void parseJSON(JsonObject jsonObject) {
                     this.restoredBy = user.new Info(userJSON);
                 } else if (memberName.equals("purged_at")) {
                     this.purgedAt = BoxDateFormat.parse(value.asString());
+                } else if (memberName.equals("file_version")) {
+                    JsonObject fileVersionJson = value.asObject();
+                    String fileVersionId = fileVersionJson.get("id").asString();
+                    this.fileVersion = new BoxFileVersion(getAPI(), fileVersionJson, fileVersionId);
                 }
             } catch (ParseException e) {
                 assert false : "A ParseException indicates a bug in the SDK.";
@@ -232,6 +237,14 @@ public Date getPurgedAt() {
         return this.purgedAt;
     }
 
+    /**
+     * Gets the file version for file version under retention.
+     * @return the file version for file version under retention.
+     */
+    public BoxFileVersion getFileVersion() {
+        return this.fileVersion;
+    }
+
     /**
      * Deletes this version of the file.
      */

src/main/java/com/box/sdk/BoxFileVersionRetention.java

@@ -73,6 +73,9 @@ public static Iterable<BoxFileVersionRetention.Info> getAll(BoxAPIConnection api
     }
 
     /**
+     * @deprecated This method will be deprecated in the future. Please use
+     * BoxRetentionPolicyAssignment.getFilesUnderRetentionForAssignmentAsync(...)
+     * and BoxRetentionPolicyAssignment.getFileVersionsUnderRetentionForAssignmentAsync(...) instead."
      * Retrieves all file version retentions matching given filters as an Iterable.
      * @param api the API connection to be used by the resource.
      * @param filter filters for the query stored in QueryFilter object.

src/main/java/com/box/sdk/BoxRetentionPolicyAssignment.java

@@ -45,6 +45,20 @@ public class BoxRetentionPolicyAssignment extends BoxResource {
     public static final URLTemplate RETENTION_POLICY_ASSIGNMENT_URL_TEMPLATE
         = new URLTemplate("retention_policy_assignments/%s");
 
+    /**
+     * The URL template used for operation with files under retention with given retention policy assignment ID.
+     */
+    public static final URLTemplate FILES_UNDER_RETENTION_URL_TEMPLATE
+            = new URLTemplate("retention_policy_assignments/%s/files_under_retention");
+
+    /**
+     * The URL template used for operation with file versions under retention with given retention policy assignment ID.
+     */
+    public static final URLTemplate FILE_VERSIONS_UNDER_RETENTION_URL_TEMPLATE
+            = new URLTemplate("retention_policy_assignments/%s/file_versions_under_retention");
+
+    private static final int DEFAULT_LIMIT = 100;
+
     /**
      * Constructs a BoxResource for a resource with a given ID.
      *
@@ -146,6 +160,68 @@ public BoxRetentionPolicyAssignment.Info getInfo(String ... fields) {
         return new Info(responseJSON);
     }
 
+    /**
+     * Retrieves all files under retention for assignment as Iterable. Default limit is 100
+     * @param fields the fields to retrieve.
+     * @return an iterable contains information about all files under retentions as Iterable.
+     */
+    public Iterable<BoxFile.Info> getFilesUnderRetention(String ... fields) {
+        return this.getFilesUnderRetention(DEFAULT_LIMIT, fields);
+    }
+
+    /**
+     * Retrieves all files under retention for assignment as Iterable.
+     * @param limit the limit of retrieved entries per page.
+     * @param fields the fields to retrieve.
+     * @return an iterable contains information about all files under retentions as Iterable.
+     */
+    public Iterable<BoxFile.Info> getFilesUnderRetention(int limit, String ... fields) {
+        QueryStringBuilder queryString = new QueryStringBuilder();
+        if (fields.length > 0) {
+            queryString.appendParam("fields", fields);
+        }
+        URL url = FILES_UNDER_RETENTION_URL_TEMPLATE.buildWithQuery(getAPI().getBaseURL(),
+                queryString.toString(), getID());
+        return new BoxResourceIterable<BoxFile.Info>(getAPI(), url, limit) {
+            @Override
+            protected BoxFile.Info factory(JsonObject jsonObject) {
+                BoxFile boxFile
+                        = new BoxFile(getAPI(), jsonObject.get("id").asString());
+                return boxFile.new Info(jsonObject);
+            }
+        };
+    }
+
+    /**
+     * Retrieves all file version under retention for assignment as Iterable. Default limit is 100.
+     * @param fields the fields to retrieve.
+     * @return an iterable contains information about all file versions under retentions as Iterable.
+     */
+    public Iterable<BoxFileVersion> getFileVersionsUnderRetention(String ... fields) {
+        return this.getFileVersionsUnderRetention(DEFAULT_LIMIT, fields);
+    }
+
+    /**
+     * Retrieves all file version under retention for assignment as Iterable.
+     * @param limit the limit of retrieved entries per page.
+     * @param fields the fields to retrieve.
+     * @return an iterable contains information about all file versions under retentions as Iterable.
+     */
+    public Iterable<BoxFileVersion> getFileVersionsUnderRetention(int limit, String ... fields) {
+        QueryStringBuilder queryString = new QueryStringBuilder();
+        if (fields.length > 0) {
+            queryString.appendParam("fields", fields);
+        }
+        URL url = FILE_VERSIONS_UNDER_RETENTION_URL_TEMPLATE.buildWithQuery(getAPI().getBaseURL(),
+                queryString.toString(), getID());
+        return new BoxResourceIterable<BoxFileVersion>(getAPI(), url, limit) {
+            @Override
+            protected BoxFileVersion factory(JsonObject jsonObject) {
+                return new BoxFileVersion(getAPI(), jsonObject, jsonObject.get("id").asString());
+            }
+        };
+    }
+
     /**
      * Contains information about the retention policy.
      */

src/test/Fixtures/BoxRetentionPolicy/GetFileVersionsUnderRetention200.json

@@ -0,0 +1,18 @@
+{
+  "entries": [{
+    "id": "123456",
+    "etag": "1",
+    "type": "file_version",
+    "sequence_id": "3",
+    "name": "Contract.pdf",
+    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
+    "file_version": {
+      "id": "1234567",
+      "type": "file_version",
+      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
+    },
+    "applied_at": "2012-12-12T10:53:43-08:00"
+  }],
+  "limit": 1000,
+  "marker": "SomeMarker"
+}

src/test/Fixtures/BoxRetentionPolicy/GetFilesUnderRetention200.json

@@ -0,0 +1,18 @@
+{
+  "entries": [{
+    "id": "12345",
+    "etag": "1",
+    "type": "file",
+    "sequence_id": "3",
+    "name": "Contract.pdf",
+    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
+    "file_version": {
+      "id": "123456",
+      "type": "file_version",
+      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
+    },
+    "applied_at": "2012-12-12T10:53:43-08:00"
+  }],
+  "limit": 1000,
+  "marker": "some marker"
+}

src/test/java/com/box/sdk/BoxRetentionPolicyAssignmentTest.java

@@ -215,4 +215,63 @@ public void testGetFileRetentionInfoSucceeds() throws IOException {
         Assert.assertEquals(retentionPolicyName, policyInfo.getWinningPolicy().getPolicyName());
         Assert.assertEquals(fileVersionID, policyInfo.getFileVersion().getID());
     }
+
+    @Test
+    @Category(UnitTest.class)
+    public void testGetFilesUnderRetentionSucceeds() throws IOException {
+        String result = "";
+        final String retentionAssignmentID = "12345";
+        final String filesUnderRetentionURL = "/retention_policy_assignments/"
+                + retentionAssignmentID + "/files_under_retention";
+        final String fileId = "12345";
+        final String fileName = "Contract.pdf";
+        final String fileVersionID = "123456";
+
+        result = TestConfig.getFixture("BoxRetentionPolicy/GetFilesUnderRetention200");
+
+        WIRE_MOCK_CLASS_RULE.stubFor(WireMock.get(WireMock.urlPathEqualTo(filesUnderRetentionURL))
+                .willReturn(WireMock.aResponse()
+                        .withHeader("Content-Type", "application/json")
+                        .withBody(result)));
+
+        BoxRetentionPolicyAssignment retetionAssignment =
+                new BoxRetentionPolicyAssignment(this.api, retentionAssignmentID);
+        Iterator<BoxFile.Info> filesUnderRetention = retetionAssignment.getFilesUnderRetention().iterator();
+
+        BoxFile.Info firstFileUnderRetention = filesUnderRetention.next();
+
+        Assert.assertEquals(fileId, firstFileUnderRetention.getID());
+        Assert.assertEquals(fileName, firstFileUnderRetention.getName());
+        Assert.assertEquals(fileVersionID, firstFileUnderRetention.getVersion().getVersionID());
+    }
+
+    @Test
+    @Category(UnitTest.class)
+    public void testGetFileVersionsUnderRetentionSucceeds() throws IOException {
+        String result = "";
+        final String retentionAssignmentID = "12345";
+        final String filesUnderRetentionURL = "/retention_policy_assignments/"
+                + retentionAssignmentID + "/file_versions_under_retention";
+        final String fileId = "123456";
+        final String fileName = "Contract.pdf";
+        final String fileVersionID = "1234567";
+
+        result = TestConfig.getFixture("BoxRetentionPolicy/GetFileVersionsUnderRetention200");
+
+        WIRE_MOCK_CLASS_RULE.stubFor(WireMock.get(WireMock.urlPathEqualTo(filesUnderRetentionURL))
+                .willReturn(WireMock.aResponse()
+                        .withHeader("Content-Type", "application/json")
+                        .withBody(result)));
+
+        BoxRetentionPolicyAssignment retetionAssignment =
+                new BoxRetentionPolicyAssignment(this.api, retentionAssignmentID);
+        Iterator<BoxFileVersion> fileVersionsUnderRetention =
+                retetionAssignment.getFileVersionsUnderRetention().iterator();
+
+        BoxFileVersion firstFileVersionUnderRetention = fileVersionsUnderRetention.next();
+
+        Assert.assertEquals(fileId, firstFileVersionUnderRetention.getID());
+        Assert.assertEquals(fileName, firstFileVersionUnderRetention.getName());
+        Assert.assertEquals(fileVersionID, firstFileVersionUnderRetention.getFileVersion().getVersionID());
+    }
 }