Multizones

doc/storage_policy.md

@@ -0,0 +1,124 @@
+Storage Policy 
+==============
+
+Allows the enterprise admin to manage the Storage Policies for users in their
+enterprise. Used for an enterprise to decide storage location for users based on
+where they work/reside. 
+
+* [Get Storage Policy](#get-storage-policy) 
+* [Get List of Storage Policies](#get-list-of-storage-policies)
+* [Create New Assignment](#create-new-assignment)
+* [Get Assignment](#get-assignment)
+* [Get Assignment For Target](#get-assignment-for-target)
+* [Update Existing Assignment](#update-existing-assignment)
+* [Assign Storage Policy](#assign-storage-policy)
+* [Delete Assignment](#delete-assignment)
+
+Get Storage Policy
+------------------
+
+Calling [`getInfo(String fields ...)`][get-info] will return BoxStoragePolicy.Info object
+containing information about the storage policy. If necessary to retrieve 
+limited set of fields. It is possible to specify them using param.
+
+```java
+BoxStoragePolicy storagePolicy = new BoxStoragePolicy(api, id);
+BoxStoragePolicy.Info storagePolicyInfo = storagePolicy.getInfo();
+```
+
+[get-info]:http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicy.html#getInfo--
+
+Get List of Storage Policies
+----------------------------
+
+Calling the static [`getAll(BoxAPIConnection api)`][get-list-of-storage-policies]
+will return an iterable that will page through all of the storage policies. 
+It is possible to specify maximum number of items per response and fields to retrieve by 
+calling the static [`getAll(BoxAPIConnection api, int limit, String fields ...)`][get-list-of-storage-policies-with-fields] method. 
+
+```java
+Iterable<BoxStoragePolicy.Info> storagePolicies = BoxStoragePolicy.getAll(api);
+for (BoxStoragePolicy.Info storagePolicyInfo : storagePolicies) {
+        //Do something with the storage policy.
+}
+```
+
+[get-list-of-storage-policies]:http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicy.html#getAll--
+[get-list-of-storage-policies-with-fields]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicy.html#getAll-java.lang.String...-
+
+Create New Assignment
+---------------------
+
+To create new storage policy assignment call [`create(BoxAPIConnection api, String policyID, String userID)`][create] method. 
+
+```java
+BoxStoragePolicyAssignment.Info assignmentInfo = BoxStoragePolicyAssignment.create(api, policyID, userID);
+```
+
+[create]:http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssignment.html#create-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-
+
+Update Existing Assignment
+--------------------------
+
+Updating a storage policy assignment information is done by calling
+[`updateInfo(BoxStoragePolicyAssignment.Info updatedInfo)`][update-info].
+
+```java
+BoxStoragePolicyAssignment storagePolicyAssignment = new BoxStoragePolicyAssignment(api, "ASSIGNMENT_ID");
+BoxStoragePolicyAssignment.Info assignmentInfo = storagePolicyAssignment.new Info();
+assignmentInfo.setStoragePolicyID("NEW_STORAGE_POLICY_ID");
+storagePolicyAssignment.updateInfo(assignmentInfo);
+```
+
+[update-info]:http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssignment.html#updateInfo-com.box.sdk.BoxStoragePolicyAssignment.Info-
+
+Get Assignment
+--------------
+
+Calling [`getInfo(String fields ...)`][get-assignment] will return a BoxStoragePolicyAssignment.Info object containing information
+about the storage policy assignment. 
+
+```java
+BoxStoragePolicyAssignment storagePolicyAssignment = new BoxStoragePolicyAssignment(api, id);
+BoxStoragePolicyAssignment.Info assignmentInfo = storagePolicyAssignment.getInfo();
+```
+
+[get-assignment]:http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssignment.html#getInfo--
+
+Get Assignment for Target
+-------------------------
+
+Calling [`getAssignmentForTarget(BoxAPIConnection api, String resolvedForType, String resolvedForID)`][get-assignment-for-target] will return a BoxStorageAssignment.Info
+object containing information about the storage policy assignment. 
+
+```java
+BoxStoragePolicyAssignment.Info assignmentInfo = BoxStoragePolicyAssignment.getAssignmentForTarget(api, "user", "1234")
+```
+
+[get-assignment-for-target]:http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssignment.html#getAssignmentForTarget-com.box.BoxAPIConnection-java.lang.String-java.lang.String-
+
+Assign Storage Policy
+---------------------
+
+Calling [`assign(BoxAPIConnection api, String storagePolicyID, String userID)`][assign] will check if this user already has storage policy assigned to them. If not then a new
+this user will be assigned the specified storage policy. 
+
+```java
+BoxStoragePolicyAssignment.Info assignmentInfo = BoxStoragePolicyAssignment.assign(api, "1234", "5678");
+```
+
+[assign]:http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssigbment.html#assign-com.box.BoxAPIConnection-java.lang.String-java.lang.String-
+
+Delete Assignment
+-----------------
+
+Calling [`delete()`][delete] will remove the storage policy assignment from the user. 
+
+```java
+BoxStoragePolicyAssignment assignment = new BoxStoragePolicyAssignment(api, "dXNlcl8xMjM0");
+assignment.delete();
+```
+
+[delete]:http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssignment.html#delete--
+
+

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

@@ -138,6 +138,16 @@ void addPendingChange(String key, JsonArray value) {
         this.addPendingChange(key, (JsonValue) value);
     }
 
+    /**
+     * Adds a pending field change that needs to be sent to the API. It will be included in the JSON string the next
+     * time {@link #getPendingChanges} is called.
+     * @param key   the name of the field.
+     * @param value the new JsonObject value of the field.
+     */
+    void addPendingChange(String key, JsonObject value) {
+        this.addPendingChange(key, (JsonValue) value);
+    }
+
     void addChildObject(String fieldName, BoxJSONObject child) {
         if (child == null) {
             this.addPendingChange(fieldName, JsonValue.NULL);

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

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

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

@@ -0,0 +1,171 @@
+package com.box.sdk;
+
+import java.net.URL;
+
+import com.eclipsesource.json.JsonObject;
+import com.eclipsesource.json.JsonValue;
+import com.eclipsesource.json.ParseException;
+
+/**
+ *  Represents a BoxStoragePolicy.
+ */
+@BoxResourceType("storage_policy")
+public class BoxStoragePolicy extends BoxResource {
+
+    /**
+     * Storage Policies URL Template.
+     */
+    public static final URLTemplate STORAGE_POLICY_URL_TEMPLATE = new URLTemplate("storage_policies");
+
+    /**
+     * Storage Policies URL Template.
+     */
+    public static final URLTemplate STORAGE_POLICY_WITH_ID_URL_TEMPLATE = new URLTemplate("storage_policies/%s");
+
+    /**
+     * The default limit of entries per response.
+     */
+    private static final int DEFAULT_LIMIT = 100;
+
+    /**
+     * Constructs a BoxStoragePolicy with a given ID.
+     *
+     * @param api the API connection to be used by the BoxStoragePolicy.
+     * @param id  the ID of the BoxStoragePolicy.
+     */
+    public BoxStoragePolicy(BoxAPIConnection api, String id) {
+        super(api, id);
+    }
+
+    /**
+     * Gets information for a Box Storage Policy with optional fields.
+     *
+     * @param fields the fields to retrieve.
+     * @return info about this item containing only the specified fields, including storage policy.
+     */
+    public BoxStoragePolicy.Info getInfo(String... fields) {
+        QueryStringBuilder builder = new QueryStringBuilder();
+        if (fields.length > 0) {
+            builder.appendParam("fields", fields);
+        }
+        URL url = STORAGE_POLICY_WITH_ID_URL_TEMPLATE.buildWithQuery(this.getAPI().getBaseURL(), builder.toString(),
+                this.getID());
+
+        BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "GET");
+        BoxJSONResponse response = (BoxJSONResponse) request.send();
+        return new Info(response.getJSON());
+    }
+
+    /**
+     * Returns all BoxStoragePolicy with specified fields.
+     *
+     * @param api    the API connection to be used by the resource.
+     * @param fields the fields to retrieve.
+     * @return an iterable with all the storage policies met search conditions.
+     */
+    public static Iterable<BoxStoragePolicy.Info> getAll(final BoxAPIConnection api, String... fields) {
+
+        return getAll(api, DEFAULT_LIMIT, fields);
+    }
+
+    /**
+     * Returns all BoxStoragePolicy with specified fields.
+     *
+     * @param api    the API connection to be used by the resource.
+     * @param limit  the limit of items per single response. The default is 100.
+     * @param fields the fields to retrieve.
+     * @return an iterable with all the storage policies met search conditions.
+     */
+    public static Iterable<BoxStoragePolicy.Info> getAll(final BoxAPIConnection api, int limit, String... fields) {
+
+        QueryStringBuilder builder = new QueryStringBuilder();
+        if (fields.length > 0) {
+            builder.appendParam("fields", fields);
+        }
+
+        URL url = STORAGE_POLICY_URL_TEMPLATE.buildWithQuery(api.getBaseURL(), builder.toString());
+        return new BoxResourceIterable<BoxStoragePolicy.Info>(api, url, limit) {
+
+            @Override
+            protected BoxStoragePolicy.Info factory(JsonObject jsonObject) {
+                BoxStoragePolicy storagePolicy = new BoxStoragePolicy(api, jsonObject.get("id").asString());
+
+                return storagePolicy.new Info(jsonObject);
+            }
+        };
+    }
+
+    /**
+     * Checks if there is already a Storage Policy Assignment and creates one if one does not exist.
+     * @param userID             the ID of the user you want to assign the Storage Policy to.
+     * @return information about this {@link BoxStoragePolicyAssignment}.
+     */
+    public BoxStoragePolicyAssignment.Info assign(String userID) {
+        return BoxStoragePolicyAssignment.assign(this.getAPI(), this.getID(), userID);
+    }
+
+    /**
+     * Contains information about the BoxStoragePolicy.
+     */
+    public class Info extends BoxResource.Info {
+
+        /**
+         * @see #getStoragePolicyName()
+         */
+        private String storagePolicyName;
+
+        /**
+         * 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);
+        }
+
+        /**
+         * {@inheritDoc}
+         */
+        @Override
+        public BoxStoragePolicy getResource() {
+            return BoxStoragePolicy.this;
+        }
+
+        /**
+         * @return the name of the storage policy.
+         */
+        public String getStoragePolicyName() {
+            return this.storagePolicyName;
+        }
+
+        @Override
+        void parseJSONMember(JsonObject.Member member) {
+            super.parseJSONMember(member);
+            String memberName = member.getName();
+            JsonValue value = member.getValue();
+            try {
+                if (memberName.equals("name")) {
+                    this.storagePolicyName = value.asString();
+                }
+            } catch (ParseException e) {
+                assert false : "A ParseException indicates a bug in the SDK.";
+            }
+        }
+    }
+}