Add folder lock functionality

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 __New Features and Enhancements:__
 
+- Add folder lock functionality ([#856](https://github.com/box/box-java-sdk/pull/856))
 - Add support for search param to get shared link items ([#855](https://github.com/box/box-java-sdk/pull/855))
 
 __Bug Fixes:__

doc/folders.md

@@ -39,6 +39,9 @@ group, and perform other common folder operations (move, copy, delete, etc.).
 - [Get All Cascade Policies on Folder](#get-all-cascade-policies-on-folder)
 - [Force Apply Cascade Policy on Folder](#force-apply-cascade-policy-on-folder)
 - [Delete Cascade Policy](#delete-cascade-policy)
+- [Lock a Folder](#lock-a-folder)
+- [Get All Locks on a Folder](#get-all-locks-on-a-folder)
+- [Delete A Lock on a Folder](#delete-a-lock-on-a-folder)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -687,3 +690,41 @@ policyToDelete.delete();
 
 [delete-cascade-policy]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxMetadataCascadePolicy.html#delete--
 
+Lock a Folder
+-----------------------------
+
+To lock a folder and prevent it from being moved and/or deleted, call [`lock()`][lock] on a folder.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+FolderLock.Info folderLock = folder.lock();
+```
+
+[lock]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#lock--
+
+Get All Locks on a Folder
+-----------------------------
+
+To get all locks on a folder, call [`getlock()`][get-locks] on folder.
+
+```java
+BoxFolder folder = new BoxFolder(this.api, "id");
+Iterable<BoxFolderLock.Info> locks = folder.getLocks();
+for (BoxFolderLock.Info lockInfo : locks) {
+    // Do something with each lockInfo here
+}
+```
+
+[get-locks]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getLocks--
+
+Delete a Lock on a Folder
+-----------------------------
+
+To delete a lock on a folder, call [`delete()`][delete-lock] on a BoxFolderLock object. This cannot be called on a BoxFolder object.
+
+```java
+BoxFolderLock folderLock = new BoxFolderLock(this.api, "folderLockID");
+folderLock.delete();
+```
+
+[delete-lock]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolderLock.html#delete--

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

@@ -99,6 +99,10 @@ public enum SortDirection {
      * Upload Session URL Template.
      */
     public static final URLTemplate UPLOAD_SESSION_URL_TEMPLATE = new URLTemplate("files/upload_sessions");
+    /**
+     * Folder Locks URL Template.
+     */
+    public static final URLTemplate FOLDER_LOCK_URL_TEMPLATE = new URLTemplate("folder_locks");
 
     /**
      * Constructs a BoxFolder for a folder with a given ID.
@@ -1200,6 +1204,55 @@ public Iterable<BoxMetadataCascadePolicy.Info> getMetadataCascadePolicies(String
         return cascadePoliciesInfo;
     }
 
+    /**
+     * Lock this folder.
+     *
+     * @return a created folder lock object.
+     */
+    public BoxFolderLock.Info lock() {
+        JsonObject folderObject = new JsonObject();
+        folderObject.add("type", "folder");
+        folderObject.add("id", this.getID());
+
+        JsonObject lockedOperations = new JsonObject();
+        lockedOperations.add("move", true);
+        lockedOperations.add("delete", true);
+
+
+        JsonObject body = new JsonObject();
+        body.add("folder", folderObject);
+        body.add("locked_operations", lockedOperations);
+
+        BoxJSONRequest request =
+            new BoxJSONRequest(this.getAPI(), FOLDER_LOCK_URL_TEMPLATE.build(this.getAPI().getBaseURL()),
+                "POST");
+        request.setBody(body.toString());
+        BoxJSONResponse response = (BoxJSONResponse) request.send();
+        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
+
+        BoxFolderLock createdFolderLock = new BoxFolderLock(this.getAPI(), responseJSON.get("id").asString());
+        return createdFolderLock.new Info(responseJSON);
+    }
+
+    /**
+     * Get the lock on this folder.
+     *
+     * @return a folder lock object.
+     */
+    public Iterable<BoxFolderLock.Info> getLocks() {
+        String queryString = new QueryStringBuilder().appendParam("folder_id", this.getID()).toString();
+        final BoxAPIConnection api = this.getAPI();
+        return new BoxResourceIterable<BoxFolderLock.Info>(api,
+            FOLDER_LOCK_URL_TEMPLATE.buildWithQuery(api.getBaseURL(), queryString), 100) {
+            @Override
+            protected BoxFolderLock.Info factory(JsonObject jsonObject) {
+                BoxFolderLock folderLock =
+                        new BoxFolderLock(api, jsonObject.get("id").asString());
+                return folderLock.new Info(jsonObject);
+            }
+        };
+    }
+
     /**
      * Contains information about a BoxFolder.
      */

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

@@ -0,0 +1,176 @@
+package com.box.sdk;
+
+import java.net.URL;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.Map;
+
+import com.eclipsesource.json.JsonObject;
+import com.eclipsesource.json.JsonValue;
+
+/**
+ * Represents a lock on a folder.
+ *
+ * <p>Unless otherwise noted, the methods in this class can throw an unchecked {@link BoxAPIException} (unchecked
+ * meaning that the compiler won't force you to handle it) if an error occurs. If you wish to implement custom error
+ * handling for errors related to the Box REST API, you should capture this exception explicitly.</p>
+ */
+@BoxResourceType("folder_lock")
+public class BoxFolderLock extends BoxResource {
+    /**
+     * Delete Folder Locks URL Template.
+     */
+    public static final URLTemplate DELETE_FOLDER_LOCK_URL_TEMPLATE = new URLTemplate("folder_locks/%s");
+
+    /**
+     * Constructs a BoxFolderLock with a given ID.
+     *
+     * @param api the API connection to be used by the folder lock.
+     * @param id  the ID of the folder lock.
+     */
+    public BoxFolderLock(BoxAPIConnection api, String id) {
+        super(api, id);
+    }
+
+    /**
+     * Delete the lock on this folder.
+     */
+    public void delete() {
+        URL url = DELETE_FOLDER_LOCK_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID());
+        BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "DELETE");
+        BoxAPIResponse response = request.send();
+        response.disconnect();
+    }
+
+    /**
+     * Contains information about a BoxFolderLock.
+     */
+    public class Info extends BoxResource.Info {
+        private BoxFolder.Info folder;
+        private BoxUser.Info createdBy;
+        private Date createdAt;
+        private String lockType;
+        private Map<String, Boolean> lockedOperations;
+
+        /**
+         * Constructs an empty Info object.
+         */
+        public Info() {
+            super();
+        }
+
+        /**
+         * Constructs an Info object by parsing information from a JSON string.
+         *
+         * @param json the JSON string to parse.
+         */
+        public Info(String json) {
+            super(json);
+        }
+
+        /**
+         * Constructs an Info object using an already parsed JSON object.
+         *
+         * @param jsonObject the parsed JSON object.
+         */
+        Info(JsonObject jsonObject) {
+            super(jsonObject);
+        }
+
+        @Override
+        public BoxResource getResource() {
+            return BoxFolderLock.this;
+        }
+
+        /**
+         * Gets the folder that the lock applies to.
+         *
+         * @return The folder that the lock applies to.
+         */
+        public BoxFolder.Info getFolder() {
+            return this.folder;
+        }
+
+        /**
+         * Gets the user or group that created the lock.
+         *
+         * @return the user or group that created the lock.
+         */
+        public BoxUser.Info getCreatedBy() {
+            return this.createdBy;
+        }
+
+        /**
+         * Gets the date the folder lock object was created.
+         *
+         * @return the date the folder lock object was created.
+         */
+        public Date getCreatedAt() {
+            return this.createdAt;
+        }
+
+        /**
+         * Gets the lock type, always freeze.
+         *
+         * @return the lock type, always freeze.
+         */
+        public String getLockType() {
+            return this.lockType;
+        }
+
+        /**
+         * Gets the operations that have been locked.
+         *
+         * @return the operations that have been locked.
+         */
+        public Map<String, Boolean> getLockedOperations() {
+            return this.lockedOperations;
+        }
+
+        /**
+         * {@inheritDoc}
+         */
+        @Override
+        protected void parseJSONMember(JsonObject.Member member) {
+            super.parseJSONMember(member);
+
+            String memberName = member.getName();
+            JsonValue value = member.getValue();
+
+            try {
+                if (memberName.equals("folder")) {
+                    JsonObject folderJSON = value.asObject();
+                    String folderID = folderJSON.get("id").asString();
+                    BoxFolder folder = new BoxFolder(getAPI(), folderID);
+                    this.folder = folder.new Info(folderJSON);
+                } else if (memberName.equals("created_by")) {
+                    JsonObject userJSON = value.asObject();
+                    if (this.createdBy == null) {
+                        String userID = userJSON.get("id").asString();
+                        BoxUser user = new BoxUser(getAPI(), userID);
+                        this.createdBy = user.new Info(userJSON);
+                    } else {
+                        this.createdBy.update(userJSON);
+                    }
+                } else if (memberName.equals("created_at")) {
+                    this.createdAt = BoxDateFormat.parse(value.asString());
+
+                } else if (memberName.equals("lock_type")) {
+                    this.lockType = value.asString();
+
+                } else if (memberName.equals("locked_operations")) {
+                    JsonObject lockedOperationsJSON = value.asObject();
+                    Map<String, Boolean> operationsMap = new HashMap<String, Boolean>();
+                    for (JsonObject.Member operationMember : lockedOperationsJSON) {
+                        String operation = operationMember.getName();
+                        Boolean operationBoolean = operationMember.getValue().asBoolean();
+                        operationsMap.put(operation, operationBoolean);
+                    }
+                    this.lockedOperations = operationsMap;
+                }
+            } catch (Exception e) {
+                throw new BoxDeserializationException(memberName, value.toString(), e);
+            }
+        }
+    }
+}

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

@@ -64,6 +64,7 @@ private static Map<String, Class<? extends BoxResource>> initResourceClassByType
         result.put(getResourceType(BoxWebLink.class), BoxWebLink.class);
         result.put(getResourceType(BoxStoragePolicy.class), BoxStoragePolicy.class);
         result.put(getResourceType(BoxStoragePolicyAssignment.class), BoxStoragePolicyAssignment.class);
+        result.put(getResourceType(BoxFolderLock.class), BoxFolderLock.class);
 
         return Collections.unmodifiableMap(result);
     }

src/test/Fixtures/BoxFolder/CreateFolderLock200.json

@@ -0,0 +1,21 @@
+{
+  "id": "12345678",
+  "type": "folder_lock",
+  "created_at": "2020-09-14T23:12:53Z",
+  "created_by": {
+    "id": "11446498",
+    "type": "user"
+  },
+  "folder": {
+    "id": "12345",
+    "type": "folder",
+    "etag": "1",
+    "name": "Contracts",
+    "sequence_id": "3"
+  },
+  "lock_type": "freeze",
+  "locked_operations": {
+    "delete": true,
+    "move": true
+  }
+}

src/test/Fixtures/BoxFolder/GetFolderLocks200.json

@@ -0,0 +1,27 @@
+{
+  "entries": [
+    {
+      "folder": {
+        "id": "12345",
+        "etag": "1",
+        "type": "folder",
+        "sequence_id": "3",
+        "name": "Contracts"
+      },
+      "id": "12345678",
+      "type": "folder_lock",
+      "created_by": {
+        "id": "11446498",
+        "type": "user"
+      },
+      "created_at": "2020-09-14T23:12:53Z",
+      "locked_operations": {
+        "move": true,
+        "delete": true
+      },
+      "lock_type": "freeze"
+    }
+  ],
+  "limit": 1000,
+  "next_marker": null
+}