001package com.box.sdk; 002 003import java.net.URL; 004import java.text.ParseException; 005import java.util.Date; 006 007import com.eclipsesource.json.JsonObject; 008import com.eclipsesource.json.JsonValue; 009 010/** 011 * Represents a relationship between a user and a group. 012 * 013 * <p>Unless otherwise noted, the methods in this class can throw an unchecked {@link BoxAPIException} (unchecked 014 * meaning that the compiler won't force you to handle it) if an error occurs. If you wish to implement custom error 015 * handling for errors related to the Box REST API, you should capture this exception explicitly.</p> 016 */ 017public class BoxGroupMembership extends BoxResource { 018 private static final URLTemplate MEMBERSHIP_URL_TEMPLATE = new URLTemplate("group_memberships/%s"); 019 020 /** 021 * Constructs a BoxGroupMembership for a group membership with a given ID. 022 * @param api the API connection to be used by the group membership. 023 * @param id the ID of the group membership. 024 */ 025 public BoxGroupMembership(BoxAPIConnection api, String id) { 026 super(api, id); 027 } 028 029 /** 030 * Gets information about this group membership. 031 * @return info about this group membership. 032 */ 033 public Info getInfo() { 034 BoxAPIConnection api = this.getAPI(); 035 URL url = MEMBERSHIP_URL_TEMPLATE.build(api.getBaseURL(), this.getID()); 036 037 BoxAPIRequest request = new BoxAPIRequest(api, url, "GET"); 038 BoxJSONResponse response = (BoxJSONResponse) request.send(); 039 JsonObject jsonObject = JsonObject.readFrom(response.getJSON()); 040 return new Info(jsonObject); 041 } 042 043 /** 044 * Updates the information about this group membership with any info fields that have been modified locally. 045 * @param info the updated info. 046 */ 047 public void updateInfo(Info info) { 048 BoxAPIConnection api = this.getAPI(); 049 URL url = MEMBERSHIP_URL_TEMPLATE.build(api.getBaseURL(), this.getID()); 050 051 BoxJSONRequest request = new BoxJSONRequest(api, url, "PUT"); 052 request.setBody(info.getPendingChanges()); 053 BoxJSONResponse response = (BoxJSONResponse) request.send(); 054 JsonObject jsonObject = JsonObject.readFrom(response.getJSON()); 055 info.update(jsonObject); 056 } 057 058 /** 059 * Deletes this group membership. 060 */ 061 public void delete() { 062 BoxAPIConnection api = this.getAPI(); 063 URL url = MEMBERSHIP_URL_TEMPLATE.build(api.getBaseURL(), this.getID()); 064 065 BoxAPIRequest request = new BoxAPIRequest(api, url, "DELETE"); 066 BoxAPIResponse response = request.send(); 067 response.disconnect(); 068 } 069 070 /** 071 * Contains information about a BoxGroupMembership. 072 */ 073 public class Info extends BoxResource.Info { 074 private BoxUser.Info user; 075 private BoxGroup.Info group; 076 private Role role; 077 private Date createdAt; 078 private Date modifiedAt; 079 080 /** 081 * Constructs an empty Info object. 082 */ 083 public Info() { 084 super(); 085 } 086 087 /** 088 * Constructs an Info object by parsing information from a JSON string. 089 * @param json the JSON string to parse. 090 */ 091 public Info(String json) { 092 super(json); 093 } 094 095 /** 096 * Constructs an Info object using an already parsed JSON object. 097 * @param jsonObject the parsed JSON object. 098 */ 099 Info(JsonObject jsonObject) { 100 super(jsonObject); 101 } 102 103 /** 104 * Gets the user belonging to the group. 105 * 106 * <p>Note: the BoxUser.Info returned by this method will only have the ID, name, and login fields 107 * populated.</p> 108 * 109 * @return the user belonging to the group. 110 */ 111 public BoxUser.Info getUser() { 112 return this.user; 113 } 114 115 /** 116 * Gets the group the user belongs to. 117 * 118 * <p>Note: the BoxGroup.Info returned by this method will only have the ID and name fields populated.</p> 119 * 120 * @return the group the user belongs to. 121 */ 122 public BoxGroup.Info getGroup() { 123 return this.group; 124 } 125 126 /** 127 * Gets the level of access the user has. 128 * @return the level of access the user has. 129 */ 130 public Role getRole() { 131 return this.role; 132 } 133 134 /** 135 * Sets the level of access the user has. 136 * @param role the new level of access to give the user. 137 */ 138 public void setRole(Role role) { 139 this.role = role; 140 this.addPendingChange("role", role.toJSONString()); 141 } 142 143 /** 144 * Gets the time the group membership was created. 145 * @return the time the group membership was created. 146 */ 147 public Date getCreatedAt() { 148 return this.createdAt; 149 } 150 151 /** 152 * Gets the time the group membership was last modified. 153 * @return the time the group membership was last modified. 154 */ 155 public Date getModifiedAt() { 156 return this.modifiedAt; 157 } 158 159 @Override 160 public BoxGroupMembership getResource() { 161 return BoxGroupMembership.this; 162 } 163 164 @Override 165 protected void parseJSONMember(JsonObject.Member member) { 166 super.parseJSONMember(member); 167 168 String memberName = member.getName(); 169 JsonValue value = member.getValue(); 170 171 try { 172 if (memberName.equals("user")) { 173 JsonObject userJSON = value.asObject(); 174 if (this.user == null) { 175 String userID = userJSON.get("id").asString(); 176 BoxUser user = new BoxUser(getAPI(), userID); 177 this.user = user.new Info(userJSON); 178 } else { 179 this.user.update(userJSON); 180 } 181 182 } else if (memberName.equals("group")) { 183 JsonObject groupJSON = value.asObject(); 184 if (this.group == null) { 185 String userID = groupJSON.get("id").asString(); 186 BoxGroup group = new BoxGroup(getAPI(), userID); 187 this.group = group.new Info(groupJSON); 188 } else { 189 this.group.update(groupJSON); 190 } 191 192 } else if (memberName.equals("role")) { 193 this.role = Role.fromJSONString(value.asString()); 194 195 } else if (memberName.equals("created_at")) { 196 this.createdAt = BoxDateFormat.parse(value.asString()); 197 198 } else if (memberName.equals("modified_at")) { 199 this.modifiedAt = BoxDateFormat.parse(value.asString()); 200 201 } 202 } catch (ParseException e) { 203 assert false : "A ParseException indicates a bug in the SDK."; 204 } 205 } 206 } 207 208 /** 209 * Enumerates the possible roles that a user can have within a group. 210 */ 211 public enum Role { 212 /** 213 * The user is an administrator in the group. 214 */ 215 ADMIN ("admin"), 216 217 /** 218 * The user is a regular member in the group. 219 */ 220 MEMBER ("member"); 221 222 private final String jsonValue; 223 224 private Role(String jsonValue) { 225 this.jsonValue = jsonValue; 226 } 227 228 static Role fromJSONString(String jsonValue) { 229 return Role.valueOf(jsonValue.toUpperCase()); 230 } 231 232 String toJSONString() { 233 return this.jsonValue; 234 } 235 } 236}