Add membership related features

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

@@ -1,9 +1,14 @@
 package com.box.sdk;
 
 import java.net.URL;
+import java.util.ArrayList;
+import java.util.Collection;
 import java.util.Iterator;
 
+import com.box.sdk.BoxGroupMembership.Role;
+import com.eclipsesource.json.JsonArray;
 import com.eclipsesource.json.JsonObject;
+import com.eclipsesource.json.JsonValue;
 
 /**
  * Represents a set of Box users.
@@ -15,6 +20,8 @@
 public class BoxGroup extends BoxCollaborator {
     private static final URLTemplate GROUPS_URL_TEMPLATE = new URLTemplate("groups");
     private static final URLTemplate GROUP_URL_TEMPLATE = new URLTemplate("groups/%s");
+    private static final URLTemplate MEMBERSHIPS_URL_TEMPLATE = new URLTemplate("groups/%s/memberships");
+    private static final URLTemplate ADD_MEMBERSHIP_URL_TEMPLATE = new URLTemplate("group_memberships");
 
     /**
      * Constructs a BoxGroup for a group with a given ID.
@@ -71,6 +78,66 @@ public Info getInfo() {
         return new Info(responseJSON);
     }
 
+    /**
+     * Gets information about all of the group memberships for this group.
+     * @return a collection of information about the group memberships for this group.
+     */
+    public Collection<BoxGroupMembership.Info> getMemberships() {
+        BoxAPIConnection api = this.getAPI();
+        URL url = MEMBERSHIPS_URL_TEMPLATE.build(api.getBaseURL(), this.getID());
+
+        BoxAPIRequest request = new BoxAPIRequest(api, url, "GET");
+        BoxJSONResponse response = (BoxJSONResponse) request.send();
+        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
+
+        int entriesCount = responseJSON.get("total_count").asInt();
+        Collection<BoxGroupMembership.Info> memberships = new ArrayList<BoxGroupMembership.Info>(entriesCount);
+        JsonArray entries = responseJSON.get("entries").asArray();
+        for (JsonValue entry : entries) {
+            JsonObject entryObject = entry.asObject();
+            BoxGroupMembership membership = new BoxGroupMembership(api, entryObject.get("id").asString());
+            BoxGroupMembership.Info info = membership.new Info(entryObject);
+            memberships.add(info);
+        }
+
+        return memberships;
+    }
+
+    /**
+     * Adds a member to this group with the default role.
+     * @param  user the member to be added to this group.
+     * @return      info about the new group membership.
+     */
+    public BoxGroupMembership.Info addMembership(BoxUser user) {
+        return this.addMembership(user, null);
+    }
+
+    /**
+     * Adds a member to this group with the specified role.
+     * @param  user the member to be added to this group.
+     * @param  role the role of the user in this group. Can be null to assign the default role.
+     * @return      info about the new group membership.
+     */
+    public BoxGroupMembership.Info addMembership(BoxUser user, Role role) {
+        BoxAPIConnection api = this.getAPI();
+
+        JsonObject requestJSON = new JsonObject();
+        requestJSON.add("user", new JsonObject().add("id", user.getID()));
+        requestJSON.add("group", new JsonObject().add("id", this.getID()));
+        if (role != null) {
+            requestJSON.add("role", role.toJSONString());
+        }
+
+        URL url = ADD_MEMBERSHIP_URL_TEMPLATE.build(api.getBaseURL());
+        BoxJSONRequest request = new BoxJSONRequest(api, url, "POST");
+        request.setBody(requestJSON.toString());
+        BoxJSONResponse response = (BoxJSONResponse) request.send();
+        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
+
+        BoxGroupMembership membership = new BoxGroupMembership(api, responseJSON.get("id").asString());
+        return membership.new Info(responseJSON);
+    }
+
     /**
      * Deletes this group.
      */

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

@@ -0,0 +1,236 @@
+package com.box.sdk;
+
+import java.net.URL;
+import java.text.ParseException;
+import java.util.Date;
+
+import com.eclipsesource.json.JsonObject;
+import com.eclipsesource.json.JsonValue;
+
+/**
+ * Represents a relationship between a user and a group.
+ *
+ * <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>
+ */
+public class BoxGroupMembership extends BoxResource {
+    private static final URLTemplate MEMBERSHIP_URL_TEMPLATE = new URLTemplate("group_memberships/%s");
+
+    /**
+     * Constructs a BoxGroupMembership for a group membership with a given ID.
+     * @param  api the API connection to be used by the group membership.
+     * @param  id  the ID of the group membership.
+     */
+    public BoxGroupMembership(BoxAPIConnection api, String id) {
+        super(api, id);
+    }
+
+    /**
+     * Gets information about this group membership.
+     * @return info about this group membership.
+     */
+    public Info getInfo() {
+        BoxAPIConnection api = this.getAPI();
+        URL url = MEMBERSHIP_URL_TEMPLATE.build(api.getBaseURL(), this.getID());
+
+        BoxAPIRequest request = new BoxAPIRequest(api, url, "GET");
+        BoxJSONResponse response = (BoxJSONResponse) request.send();
+        JsonObject jsonObject = JsonObject.readFrom(response.getJSON());
+        return new Info(jsonObject);
+    }
+
+    /**
+     * Updates the information about this group membership with any info fields that have been modified locally.
+     * @param info the updated info.
+     */
+    public void updateInfo(Info info) {
+        BoxAPIConnection api = this.getAPI();
+        URL url = MEMBERSHIP_URL_TEMPLATE.build(api.getBaseURL(), this.getID());
+
+        BoxJSONRequest request = new BoxJSONRequest(api, url, "PUT");
+        request.setBody(info.getPendingChanges());
+        BoxJSONResponse response = (BoxJSONResponse) request.send();
+        JsonObject jsonObject = JsonObject.readFrom(response.getJSON());
+        info.update(jsonObject);
+    }
+
+    /**
+     * Deletes this group membership.
+     */
+    public void delete() {
+        BoxAPIConnection api = this.getAPI();
+        URL url = MEMBERSHIP_URL_TEMPLATE.build(api.getBaseURL(), this.getID());
+
+        BoxAPIRequest request = new BoxAPIRequest(api, url, "DELETE");
+        BoxAPIResponse response = request.send();
+        response.disconnect();
+    }
+
+    /**
+     * Contains information about a BoxGroupMembership.
+     */
+    public class Info extends BoxResource.Info {
+        private BoxUser.Info user;
+        private BoxGroup.Info group;
+        private Role role;
+        private Date createdAt;
+        private Date modifiedAt;
+
+        /**
+         * 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);
+        }
+
+        /**
+         * Gets the user belonging to the group.
+         *
+         * <p>Note: the BoxUser.Info returned by this method will only have the ID, name, and login fields
+         * populated.</p>
+         *
+         * @return the user belonging to the group.
+         */
+        public BoxUser.Info getUser() {
+            return this.user;
+        }
+
+        /**
+         * Gets the group the user belongs to.
+         *
+         * <p>Note: the BoxGroup.Info returned by this method will only have the ID and name fields populated.</p>
+         *
+         * @return the group the user belongs to.
+         */
+        public BoxGroup.Info getGroup() {
+            return this.group;
+        }
+
+        /**
+         * Gets the level of access the user has.
+         * @return the level of access the user has.
+         */
+        public Role getRole() {
+            return this.role;
+        }
+
+        /**
+         * Sets the level of access the user has.
+         * @param role the new level of access to give the user.
+         */
+        public void setRole(Role role) {
+            this.role = role;
+            this.addPendingChange("role", role.toJSONString());
+        }
+
+        /**
+         * Gets the time the group membership was created.
+         * @return the time the group membership was created.
+         */
+        public Date getCreatedAt() {
+            return this.createdAt;
+        }
+
+        /**
+         * Gets the time the group membership was last modified.
+         * @return the time the group membership was last modified.
+         */
+        public Date getModifiedAt() {
+            return this.modifiedAt;
+        }
+
+        @Override
+        public BoxGroupMembership getResource() {
+            return BoxGroupMembership.this;
+        }
+
+        @Override
+        protected void parseJSONMember(JsonObject.Member member) {
+            super.parseJSONMember(member);
+
+            String memberName = member.getName();
+            JsonValue value = member.getValue();
+
+            try {
+                if (memberName.equals("user")) {
+                    JsonObject userJSON = value.asObject();
+                    if (this.user == null) {
+                        String userID = userJSON.get("id").asString();
+                        BoxUser user = new BoxUser(getAPI(), userID);
+                        this.user = user.new Info(userJSON);
+                    } else {
+                        this.user.update(userJSON);
+                    }
+
+                } else if (memberName.equals("group")) {
+                    JsonObject groupJSON = value.asObject();
+                    if (this.group == null) {
+                        String userID = groupJSON.get("id").asString();
+                        BoxGroup group = new BoxGroup(getAPI(), userID);
+                        this.group = group.new Info(groupJSON);
+                    } else {
+                        this.group.update(groupJSON);
+                    }
+
+                } else if (memberName.equals("role")) {
+                    this.role = Role.fromJSONString(value.asString());
+
+                } else if (memberName.equals("created_at")) {
+                    this.createdAt = BoxDateFormat.parse(value.asString());
+
+                } else if (memberName.equals("modified_at")) {
+                    this.modifiedAt = BoxDateFormat.parse(value.asString());
+
+                }
+            } catch (ParseException e) {
+                assert false : "A ParseException indicates a bug in the SDK.";
+            }
+        }
+    }
+
+    /**
+     * Enumerates the possible roles that a user can have within a group.
+     */
+    public enum Role {
+        /**
+         * The user is an administrator in the group.
+         */
+        ADMIN ("admin"),
+
+        /**
+         * The user is a regular member in the group.
+         */
+        MEMBER ("member");
+
+        private final String jsonValue;
+
+        private Role(String jsonValue) {
+            this.jsonValue = jsonValue;
+        }
+
+        static Role fromJSONString(String jsonValue) {
+            return Role.valueOf(jsonValue.toUpperCase());
+        }
+
+        String toJSONString() {
+            return this.jsonValue;
+        }
+    }
+}

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

@@ -31,6 +31,7 @@ public class BoxUser extends BoxCollaborator {
     private static final URLTemplate USER_URL_TEMPLATE = new URLTemplate("users/%s");
     private static final URLTemplate GET_ME_URL = new URLTemplate("users/me");
     private static final URLTemplate USERS_URL_TEMPLATE = new URLTemplate("users");
+    private static final URLTemplate USER_MEMBERSHIPS_URL_TEMPLATE = new URLTemplate("users/%s/memberships");
     private static final URLTemplate EMAIL_ALIAS_URL_TEMPLATE = new URLTemplate("users/%s/email_aliases/%s");
     private static final URLTemplate EMAIL_ALIASES_URL_TEMPLATE = new URLTemplate("users/%s/email_aliases");
 
@@ -167,6 +168,34 @@ public BoxUser.Info getInfo(String... fields) {
         return new Info(jsonObject);
     }
 
+    /**
+     * Gets information about all of the group memberships for this user.
+     *
+     * <p>Note: This method is only available to enterprise admins.</p>
+     *
+     * @return a collection of information about the group memberships for this user.
+     */
+    public Collection<BoxGroupMembership.Info> getMemberships() {
+        BoxAPIConnection api = this.getAPI();
+        URL url = USER_MEMBERSHIPS_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID());
+
+        BoxAPIRequest request = new BoxAPIRequest(api, url, "GET");
+        BoxJSONResponse response = (BoxJSONResponse) request.send();
+        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
+
+        int entriesCount = responseJSON.get("total_count").asInt();
+        Collection<BoxGroupMembership.Info> memberships = new ArrayList<BoxGroupMembership.Info>(entriesCount);
+        JsonArray entries = responseJSON.get("entries").asArray();
+        for (JsonValue entry : entries) {
+            JsonObject entryObject = entry.asObject();
+            BoxGroupMembership membership = new BoxGroupMembership(api, entryObject.get("id").asString());
+            BoxGroupMembership.Info info = membership.new Info(entryObject);
+            memberships.add(info);
+        }
+
+        return memberships;
+    }
+
     /**
      * Adds a new email alias to this user's account.
      * @param  email the email address to add as an alias.