Support for uploading file with description

doc/files.md

@@ -152,8 +152,19 @@ BoxFile.Info newFileInfo = rootFolder.uploadFile(stream, "My File.txt", 1024, ne
 stream.close();
 ```
 
+We also support the ability to attach a description of the file upon upload by calling the
+[`uploadFile(InputStream fileContents, String fileName, String fileDescription)`][upload3] method.
+
+```java
+BoxFolder rootFolder = BoxFolder.getRootFolder(api);
+FileInputStream stream = new FileInputStream("My File.txt");
+BoxFile.Info newFileInfo = rootFolder.uploadFile(stream, "My File.txt", "File Description");
+stream.close();
+```
+
 [upload]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#uploadFile-java.io.InputStream-java.lang.String-
 [upload2]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#uploadFile-java.io.InputStream-java.lang.String-long-com.box.sdk.ProgressListener-
+[upload3]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#uploadFile-java.io.InputStream-java.lang.String-java.lang.String-
 [box-folder]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html
 
 Upload Preflight Check

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

@@ -473,6 +473,22 @@ public BoxFile.Info uploadFile(InputStream fileContent, String name, long fileSi
         return this.uploadFile(uploadInfo);
     }
 
+    /**
+     * Uploads a new file to this folder with a specified file description.
+     *
+     * @param fileContent a stream containing the contents of the file to upload.
+     * @param name        the name to give the uploaded file.
+     * @param description the description to give the uploaded file.
+     * @return the uploaded file's info.
+     */
+    public BoxFile.Info uploadFile(InputStream fileContent, String name, String description) {
+        FileUploadParams uploadInfo = new FileUploadParams()
+                .setContent(fileContent)
+                .setName(name)
+                .setDescription(description);
+        return this.uploadFile(uploadInfo);
+    }
+
     /**
      * Uploads a new file to this folder with custom upload parameters.
      *
@@ -501,6 +517,10 @@ public BoxFile.Info uploadFile(FileUploadParams uploadParams) {
             request.setContentSHA1(uploadParams.getSHA1());
         }
 
+        if (uploadParams.getDescription() != null) {
+            fieldJSON.add("description", uploadParams.getDescription());
+        }
+
         request.putField("attributes", fieldJSON.toString());
 
         if (uploadParams.getSize() > 0) {

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

@@ -15,6 +15,7 @@ public class FileUploadParams {
     private long size;
     private ProgressListener listener;
     private String sha1;
+    private String description;
 
     /**
      * Constructs a new FileUploadParams with default parameters.
@@ -164,4 +165,22 @@ public FileUploadParams setSHA1(String sha1) {
     public String getSHA1() {
         return this.sha1;
     }
+
+    /**
+     * Gets the file's description set for uploading.
+     * @return the file description.
+     */
+    public String getDescription() {
+        return this.description;
+    }
+
+    /**
+     * Sets the file description during the file upload.
+     * @param description the description of the file.
+     * @return            this FileUploadParams for chaining.
+     */
+    public FileUploadParams setDescription(String description) {
+        this.description = description;
+        return this;
+    }
 }

src/test/Fixtures/BoxFile/CreateFileWithDescription201.json

@@ -0,0 +1,66 @@
+{
+  "total_count": 1,
+  "entries": [
+    {
+      "type": "file",
+      "id": "11111",
+      "file_version": {
+        "type": "file_version",
+        "id": "22222",
+        "sha1": "13f59ca81ca01c147b7c425183bbd058e680331f"
+      },
+      "sequence_id": "0",
+      "etag": "0",
+      "sha1": "13f59ca81ca01c147b7c425183bbd058e680331f",
+      "name": "Test File.txt",
+      "description": "Test Description",
+      "size": 9,
+      "path_collection": {
+        "total_count": 1,
+        "entries": [
+          {
+            "type": "folder",
+            "id": "0",
+            "sequence_id": null,
+            "etag": null,
+            "name": "All Files"
+          }
+        ]
+      },
+      "created_at": "2019-03-31T16:21:22-07:00",
+      "modified_at": "2019-03-31T16:21:22-07:00",
+      "trashed_at": null,
+      "purged_at": null,
+      "content_created_at": "2019-03-31T16:21:22-07:00",
+      "content_modified_at": "2019-03-31T16:21:22-07:00",
+      "created_by": {
+        "type": "user",
+        "id": "55555",
+        "name": "Test User",
+        "login": "testuser@example.com"
+      },
+      "modified_by": {
+        "type": "user",
+        "id": "55555",
+        "name": "TestUser",
+        "login": "testuser@example.com"
+      },
+      "owned_by": {
+        "type": "user",
+        "id": "55555",
+        "name": "Test User",
+        "login": "testuser@example.com"
+      },
+      "shared_link": null,
+      "parent": {
+        "type": "folder",
+        "id": "0",
+        "sequence_id": null,
+        "etag": null,
+        "name": "All Files"
+      },
+      "item_status": "active"
+    }
+  ]
+}
+

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

@@ -1335,6 +1335,31 @@ public void testDeleteClassification() throws IOException {
         folder.deleteClassification();
     }
 
+    @Test
+    @Category(UnitTest.class)
+    public void testUploadFileWithDescriptionSucceeds() throws IOException {
+        String result = "";
+        final String folderID = "12345";
+        final String fileURL = "/files/content";
+        final String fileContent = "Test file";
+        final String fileName = "Test File.txt";
+        final String fileDescription = "Test Description";
+        InputStream stream = new ByteArrayInputStream(fileContent.getBytes(StandardCharsets.UTF_8));
+
+        result = TestConfig.getFixture("BoxFile/CreateFileWithDescription201");
+
+        WIRE_MOCK_CLASS_RULE.stubFor(WireMock.post(WireMock.urlPathEqualTo(fileURL))
+               .willReturn(WireMock.aResponse()
+                       .withHeader("Content-Type", "application/json-patch+json")
+                       .withBody(result)
+                       .withStatus(201)));
+
+        BoxFolder folder = new BoxFolder(this.api, folderID);
+        BoxFile.Info file = folder.uploadFile(stream, fileName, fileDescription);
+
+        Assert.assertEquals(fileDescription, file.getDescription());
+    }
+
     private void getUploadSessionStatus(BoxFileUploadSession session) {
         BoxFileUploadSession.Info sessionInfo = session.getStatus();
         Assert.assertNotNull(sessionInfo.getSessionExpiresAt());