Add support for sorting folder items (#694)

doc/folders.md

@@ -84,7 +84,20 @@ for (BoxItem.Info itemInfo : folder) {
 }
 ```
 
+We also allow users to sort the results of the folder items by `name`, `id`, or `date`. This will maintain the integrity
+of the ordering when you retrieve the items for a folder. You can do this by calling the 
+[`getChildren(String sortField, BoxFolder.SortDirection sortDirection, String... fields)`][get-items-with-sort] method.
+
+```java
+BoxFolder folder = new BoxFolder(this.api, "12345");
+Iterator<BoxItem.Info> itemIterator = folder.getChildren("name", BoxFolder.SortDirection.ASC).iterator();
+for (BoxItem.Info itemInfo : itemIterator) {
+    // Do something
+}
+```
+
 [iterator]: https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#iterator--
+[get-items-with-sort]: https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getChildren-java.lang.String-com.box.sdk.BoxFolder.SortDirection-java.lang.String...-
 
 Get a Folder's Information
 --------------------------

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

@@ -35,6 +35,21 @@ public class BoxFolder extends BoxItem implements Iterable<BoxItem.Info> {
         "item_status", "item_collection", "sync_state", "has_collaborations", "permissions", "tags",
         "can_non_owners_invite", "collections", "watermark_info", "metadata"};
 
+    /**
+     * Used to specify what direction to sort and display results.
+     */
+    public enum SortDirection {
+        /**
+         * ASC for ascending order.
+         */
+        ASC,
+
+        /**
+         * DESC for descending order.
+         */
+        DESC
+    }
+
     /**
      * Create Folder URL Template.
      */
@@ -639,6 +654,31 @@ public Iterator<BoxItem.Info> iterator() {
         };
     }
 
+    /**
+     * Returns an iterable containing the items in this folder sorted by name and direction.
+     * @param sort the field to sort by, can be set as `name`, `id`, and `date`.
+     * @param direction the direction to display the item results.
+     * @param fields the fields to retrieve.
+     * @return an iterable containing the items in this folder.
+     */
+    public Iterable<BoxItem.Info> getChildren(String sort, SortDirection direction, final String... fields) {
+        QueryStringBuilder builder = new QueryStringBuilder()
+                .appendParam("sort", sort)
+                .appendParam("direction", direction.toString());
+
+        if (fields.length > 0) {
+            builder.appendParam("fields", fields).toString();
+        }
+        final String query = builder.toString();
+        return new Iterable<BoxItem.Info>() {
+            @Override
+            public Iterator<BoxItem.Info> iterator() {
+                URL url = GET_ITEMS_URL.buildWithQuery(getAPI().getBaseURL(), query, getID());
+                return new BoxItemIterator(getAPI(), url);
+            }
+        };
+    }
+
     /**
      * Retrieves a specific range of child items in this folder.
      *

src/test/Fixtures/BoxFolder/GetFolderItemsWithSort200.json

@@ -0,0 +1,100 @@
+{
+  "total_count": 10,
+  "entries": [
+    {
+      "type": "folder",
+      "id": "12345",
+      "sequence_id": "0",
+      "etag": "0",
+      "name": "Test"
+    },
+    {
+      "type": "folder",
+      "id": "56781",
+      "sequence_id": "0",
+      "etag": "0",
+      "name": "Test 2"
+    },
+    {
+      "type": "file",
+      "id": "11111",
+      "sha1": "fcd25218f7190f6d0a07d6ce03e933d3d8270851",
+      "file_version": {
+        "type": "file_version",
+        "id": "54323",
+        "sha1": "fcd25219f7190f6d0a06d6ce03e933d3d8270851"
+      },
+      "sequence_id": "17",
+      "etag": "17",
+      "name": "Test File.jpg"
+    },
+    {
+      "type": "file",
+      "id": "22222",
+      "file_version": {
+        "type": "file_version",
+        "id": "56781",
+        "sha1": "39512b7b8d16d13fdbaab6e4fc5e2d58c87d4c16"
+      },
+      "sequence_id": "3",
+      "etag": "3",
+      "sha1": "39512b8b8d16d15fdbaab6e4fb5e2d58c87d4c16",
+      "name": "Test File 2.jpg"
+    },
+    {
+      "type": "file",
+      "id": "3333",
+      "file_version": {
+        "type": "file_version",
+        "id": "12345",
+        "sha1": "8d0988e5ea5b330c529df6a8dcf3066815c6d218"
+      },
+      "sequence_id": "1",
+      "etag": "1",
+      "sha1": "8d0988e6ea5b310c529df6a8dcf3066815c6d218",
+      "name": "Test File 3.jpg"
+    },
+    {
+      "type": "file",
+      "id": "55555",
+      "file_version": {
+        "type": "file_version",
+        "id": "23424",
+        "sha1": "4066a921b78546f3e8146725d037a96236442764"
+      },
+      "sequence_id": "3",
+      "etag": "3",
+      "sha1": "4066a925b78546f2e8146725d037a96236442764",
+      "name": "Test File 4.jpg"
+    },
+    {
+      "type": "file",
+      "id": "77777",
+      "file_version": {
+        "type": "file_version",
+        "id": "32242",
+        "sha1": "a9225c82fdcm3e5701111976de462c22a76df7ee"
+      },
+      "sequence_id": "1",
+      "etag": "1",
+      "sha1": "a9225c82fdce3g5701111976de462c22a76df7ee",
+      "name": "Test File 5.jpg"
+    },
+    {
+      "type": "web_link",
+      "id": "77777",
+      "sequence_id": "1",
+      "etag": "1",
+      "name": "google.com",
+      "url": "https://test.com"
+    },
+    {
+      "type": "web_link",
+      "id": "88888",
+      "sequence_id": "0",
+      "etag": "0",
+      "name": "test.com",
+      "url": "https://example.com"
+    }
+  ]
+}

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

@@ -1360,6 +1360,36 @@ public void testUploadFileWithDescriptionSucceeds() throws IOException {
         Assert.assertEquals(fileDescription, file.getDescription());
     }
 
+    @Test
+    @Category(UnitTest.class)
+    public void testGetFolderItemsWithSort() throws IOException {
+        String result = "";
+        final String folderID = "12345";
+        final String sortField = "name";
+        final String folderItemsURL = "/folders/" + folderID + "/items/";
+
+        result = TestConfig.getFixture("BoxFolder/GetFolderItemsWithSort200");
+
+        WIRE_MOCK_CLASS_RULE.stubFor(WireMock.get(WireMock.urlPathEqualTo(folderItemsURL))
+                .withQueryParam("sort", WireMock.equalTo("name"))
+                .withQueryParam("direction", WireMock.equalTo("ASC"))
+                .withQueryParam("fields", WireMock.equalTo("name"))
+                .withQueryParam("limit", WireMock.equalTo("1000"))
+                .withQueryParam("offset", WireMock.equalTo("0"))
+                .willReturn(WireMock.aResponse()
+                       .withHeader("Content-Type", "application/json")
+                       .withBody(result)
+                       .withStatus(200)));
+
+        BoxFolder folder = new BoxFolder(this.api, "12345");
+        Iterator<BoxItem.Info> itemIterator = folder.getChildren("name",
+                BoxFolder.SortDirection.ASC, "name").iterator();
+        BoxItem.Info boxItem1 = itemIterator.next();
+        Assert.assertEquals("Test", boxItem1.getName());
+        BoxItem.Info boxItem2 =  itemIterator.next();
+        Assert.assertEquals("Test 2", boxItem2.getName());
+    }
+
     private void getUploadSessionStatus(BoxFileUploadSession session) {
         BoxFileUploadSession.Info sessionInfo = session.getStatus();
         Assert.assertNotNull(sessionInfo.getSessionExpiresAt());