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