Support for Set Metadata (#697)

doc/files.md

@@ -31,9 +31,8 @@ file's contents, upload new versions, and perform other common file operations
 - [Add a Collaborator](#add-a-collaborator)
 - [Get an Embed Link](#get-an-embed-link)
 - [Get Thumbnail](#get-thumbnail)
-- [Create Metadata](#create-metadata)
+- [Set Metadata](#set-metadata)
 - [Get Metadata](#get-metadata)
-- [Update Metadata](#update-metadata)
 - [Delete Metadata](#delete-metadata)
 - [Get All Metadata on File](#get-all-metadata-on-file)
 - [Set Classification on File](#set-classification-on-file)
@@ -626,23 +625,49 @@ byte[] thumbnail = file.getThumbnail(BoxFile.ThumbnailFileType.PNG, 256, 256, 25
 
 [get-thumbnail]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getThumbnail-com.box.sdk.BoxFile.ThumbnailFileType-int-int-int-int-
 
-Create Metadata
----------------
+Set Metadata
+------------
+
+To set metadata on a file, call [`setMetadata(String templateKey, String templateScope, Metadata properties)`][set-metadata].
+
+```java
+BoxFile file = new BoxFile(api, "id");
+file.setMetadata("test_template", "enterprise", new Metadata().add("/foo", "bar"));
+```
+
+Note: This method will unconditionally apply the provided metadata, overwriting existing metadata for the keys provided.
+To specifically create or update metadata, please refer to the `createMetadata()` and `updateMetadata()` methods.
 
 Metadata can be created on a file by calling
 [`createMetadata(Metadata properties)`][create-metadata],
 [`createMetadata(String templateKey, Metadata properties)`][create-metadata-2], or
 [`createMetadata(String templateKey, String templateScope, Metadata properties)`][create-metadata-3].
 
+Note: This method will only succeed if the provided metadata template is not currently applied to the file, otherwise
+it will fail with a Conflict error.
+
 ```java
 // Add property "foo" with value "bar" to the default metadata properties
 BoxFile file = new BoxFile(api, "id");
 file.createMetadata(new Metadata().add("/foo", "bar"));
 ```
 
+Update a files Metadata by calling [`updateMetadata(Metadata properties)`][update-metadata].
+
+```java
+BoxFile file = new BoxFile(api, "id");
+file.updateMetadata(new Metadata().add("/foo", "bar"));
+```
+
+Note: This method will only succeed if the provided metadata template has already been applied to the file; if the file
+does not have existing metadata, this method will fail with a Not Found error. This is useful in cases where you know
+the file will already have metadata applied, since it will save an API call compared to `setMetadata()`.
+
+[set-metadata]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#setMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-
 [create-metadata]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#createMetadata-com.box.sdk.Metadata-
 [create-metadata-2]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#createMetadata-java.lang.String-com.box.sdk.Metadata-
 [create-metadata-3]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#createMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-
+[update-metadata]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#updateMetadata-com.box.sdk.Metadata-
 
 Get Metadata
 ------------

doc/folders.md

@@ -22,6 +22,7 @@ group, and perform other common folder operations (move, copy, delete, etc.).
 - [Share a Folder](#share-a-folder)
 - [Get All Collaborations for a Folder](#get-all-collaborations-for-a-folder)
 - [Create Metadata](#create-metadata)
+- [Set Metadata](#set-metadata)
 - [Get Metadata](#get-metadata)
 - [Update Metadata](#update-metadata)
 - [Delete Metadata](#delete-metadata)
@@ -298,23 +299,42 @@ Collection<BoxCollaboration.Info> collaborations = folder.getCollaborations();
 
 [get-collaborations]: https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getCollaborations--
 
-Create Metadata
----------------
+Set Metadata
+------------
+
+To set metadata on a folder, call [`setMetadata(String templateKey, String templateScope, Metadata properties)`][set-metadata].
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+folder.setMetadata("test_template", "enterprise", new Metadata().add("/foo", "bar"));
+```
+
+Note: This method will unconditionally apply the provided metadata, overwriting existing metadata for the keys provided.
+To specifically create or update metadata, please refer to the `createMetadata()` and `updateMetadata()` methods.
 
 Metadata can be created on a folder by calling
 [`createMetadata(Metadata properties)`][create-metadata],
 [`createMetadata(String templateKey, Metadata properties)`][create-metadata-2], or
 [`createMetadata(String templateKey, String templateScope, Metadata properties)`][create-metadata-3]
 
+Note: This method will only succeed if the provided metadata template is not currently applied to the folder, otherwise
+it will fail with a Conflict error.
+
 ```java
 BoxFolder folder = new BoxFolder(api, "id");
 folder.createMetadata(new Metadata().add("/foo", "bar"));
 ```
 
+Note: This method will only succeed if the provided metadata template has already been applied to the folder; if the 
+folder does not have existing metadata, this method will fail with a Not Found error. This is useful in cases where you 
+know the folder will already have metadata applied, since it will save an API call compared to `setMetadata()`.
+
+[set-metadata]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#setMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-
 [create-metadata]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createMetadata-com.box.sdk.Metadata-
 [create-metadata-2]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createMetadata-java.lang.String-com.box.sdk.Metadata-
 [create-metadata-3]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-
 
+
 Get Metadata
 ------------
 

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

@@ -1038,6 +1038,44 @@ public Metadata createMetadata(String typeName, String scope, Metadata metadata)
         return new Metadata(JsonObject.readFrom(response.getJSON()));
     }
 
+    /**
+     * Sets the provided metadata on the file, overwriting any existing metadata keys already present.
+     *
+     * @param templateName the name of the metadata template.
+     * @param scope        the scope of the template (usually "global" or "enterprise").
+     * @param metadata     the new metadata values.
+     * @return the metadata returned from the server.
+     */
+    public Metadata setMetadata(String templateName, String scope, Metadata metadata) {
+        Metadata metadataValue = null;
+
+        try {
+            metadataValue = this.createMetadata(templateName, scope, metadata);
+        } catch (BoxAPIException e) {
+            if (e.getResponseCode() == 409) {
+                Metadata metadataToUpdate = new Metadata(scope, templateName);
+                for (JsonValue value : metadata.getOperations()) {
+                    if (value.asObject().get("value").isNumber()) {
+                        metadataToUpdate.add(value.asObject().get("path").asString(),
+                                value.asObject().get("value").asFloat());
+                    } else if (value.asObject().get("value").isString()) {
+                        metadataToUpdate.add(value.asObject().get("path").asString(),
+                                value.asObject().get("value").asString());
+                    } else if (value.asObject().get("value").isArray()) {
+                        ArrayList<String> list = new ArrayList<String>();
+                        for (JsonValue jsonValue : value.asObject().get("value").asArray()) {
+                            list.add(jsonValue.asString());
+                        }
+                        metadataToUpdate.add(value.asObject().get("path").asString(), list);
+                    }
+                }
+                metadataValue = this.updateMetadata(metadataToUpdate);
+            }
+        }
+
+        return metadataValue;
+    }
+
     /**
      * Adds a metadata classification to the specified file.
      *

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

@@ -856,6 +856,44 @@ public Metadata createMetadata(String templateName, String scope, Metadata metad
         return new Metadata(JsonObject.readFrom(response.getJSON()));
     }
 
+    /**
+     * Sets the provided metadata on the folder, overwriting any existing metadata keys already present.
+     *
+     * @param templateName the name of the metadata template.
+     * @param scope        the scope of the template (usually "global" or "enterprise").
+     * @param metadata     the new metadata values.
+     * @return the metadata returned from the server.
+     */
+    public Metadata setMetadata(String templateName, String scope, Metadata metadata) {
+        Metadata metadataValue = null;
+
+        try {
+            metadataValue = this.createMetadata(templateName, scope, metadata);
+        } catch (BoxAPIException e) {
+            if (e.getResponseCode() == 409) {
+                Metadata metadataToUpdate = new Metadata(scope, templateName);
+                for (JsonValue value : metadata.getOperations()) {
+                    if (value.asObject().get("value").isNumber()) {
+                        metadataToUpdate.add(value.asObject().get("path").asString(),
+                                value.asObject().get("value").asFloat());
+                    } else if (value.asObject().get("value").isString()) {
+                        metadataToUpdate.add(value.asObject().get("path").asString(),
+                                value.asObject().get("value").asString());
+                    } else if (value.asObject().get("value").isArray()) {
+                        ArrayList<String> list = new ArrayList<String>();
+                        for (JsonValue jsonValue : value.asObject().get("value").asArray()) {
+                            list.add(jsonValue.asString());
+                        }
+                        metadataToUpdate.add(value.asObject().get("path").asString(), list);
+                    }
+                }
+                metadataValue = this.updateMetadata(metadataToUpdate);
+            }
+        }
+
+        return metadataValue;
+    }
+
     /**
      * Gets the global properties metadata on this folder.
      *

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

@@ -360,6 +360,14 @@ public String getPatch() {
         return this.operations.toString();
     }
 
+    /**
+     * Returns an array of operations on metadata.
+     * @return a JSON array of operations.
+     */
+    public JsonArray getOperations() {
+        return this.operations;
+    }
+
     /**
      * Returns the JSON representation of this metadata.
      * @return the JSON representation of this metadata.

src/test/Fixtures/BoxException/BoxResponseException409.json

@@ -0,0 +1,4 @@
+{
+  "status": 409,
+  "code": "Conflict"
+}

src/test/Fixtures/BoxFile/UpdateMetadataOnFile200.json

@@ -0,0 +1,12 @@
+{
+  "test":"text",
+  "test2":2,
+  "test3":["first", "second", "third"],
+  "$type":"account-e68798f0-347f-4882-a1ae-f65b032780ac",
+  "$parent":"file_12345",
+  "$id":"0db91053-c355-4fc7-b69c-9d511974bbc4",
+  "$version":1,"$typeVersion":1,
+  "$template":"testtemplate",
+  "$scope":"enterprise_11111",
+  "$canEdit":true
+}

src/test/Fixtures/BoxFolder/UpdateMetadataOnFolder200.json

@@ -0,0 +1,12 @@
+{
+  "test":"text",
+  "test2":2,
+  "test3":["first", "second", "third"],
+  "$type":"account-e68798f0-347f-4882-a1ae-f65b032780ac",
+  "$parent":"folder_12345",
+  "$id":"0db91053-c355-4fc7-b69c-9d511974bbc4",
+  "$version":1,"$typeVersion":1,
+  "$template":"testtemplate",
+  "$scope":"enterprise_11111",
+  "$canEdit":true
+}

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

@@ -1641,6 +1641,75 @@ public void testDeleteClassification() throws IOException {
         file.deleteClassification();
     }
 
+    @Test
+    @Category(UnitTest.class)
+    public void testSetMetadataReturnsCorrectly() throws IOException {
+        String postResult = "";
+        String putResult = "";
+        final String fileID = "12345";
+        final String metadataURL = "/files/" + fileID + "/metadata/enterprise/testtemplate";
+        ArrayList<String> values = new ArrayList<String>();
+        values.add("first");
+        values.add("second");
+        values.add("third");
+
+        postResult = TestConfig.getFixture("/BoxException/BoxResponseException409");
+        putResult = TestConfig.getFixture("/BoxFile/UpdateMetadataOnFile200");
+
+        JsonArray array = new JsonArray()
+                .add("first")
+                .add("second")
+                .add("third");
+
+        JsonObject firstAttribute = new JsonObject()
+                .add("op", "add")
+                .add("path", "/test")
+                .add("value", "text");
+
+        JsonObject secondAttribute = new JsonObject()
+                .add("op", "add")
+                .add("path", "/test2")
+                .add("value", 2);
+
+        JsonObject thirdAttribute = new JsonObject()
+                .add("op", "add")
+                .add("path", "/test3")
+                .add("value", array);
+
+        JsonArray jsonArray = new JsonArray()
+                .add(firstAttribute)
+                .add(secondAttribute)
+                .add(thirdAttribute);
+
+        WIRE_MOCK_CLASS_RULE.stubFor(WireMock.post(WireMock.urlPathEqualTo(metadataURL))
+                .willReturn(WireMock.aResponse()
+                       .withHeader("Content-Type", "application/json")
+                       .withBody(postResult)
+                       .withStatus(409)));
+
+        WIRE_MOCK_CLASS_RULE.stubFor(WireMock.put(WireMock.urlPathEqualTo(metadataURL))
+                .withRequestBody(WireMock.equalToJson(jsonArray.toString()))
+                .withHeader("Content-Type", WireMock.equalTo("application/json-patch+json"))
+                .willReturn(WireMock.aResponse()
+                       .withHeader("Content-Type", "application/json-patch+json")
+                       .withBody(putResult)
+                       .withStatus(200)));
+
+        BoxFile file = new BoxFile(this.api, "12345");
+
+        Metadata metadata = new Metadata()
+                .add("/test", "text")
+                .add("/test2", 2)
+                .add("/test3", values);
+
+        Metadata metadataValues = file.setMetadata("testtemplate", "enterprise", metadata);
+
+        Assert.assertEquals("file_12345", metadataValues.getParentID());
+        Assert.assertEquals("testtemplate", metadataValues.getTemplateName());
+        Assert.assertEquals("enterprise_11111", metadataValues.getScope());
+        Assert.assertEquals("text", metadataValues.getString("/test"));
+    }
+
     private BoxFile.Info parallelMuliputUpload(File file, BoxFolder folder, String fileName)
             throws IOException, InterruptedException {
         FileInputStream newStream = new FileInputStream(file);