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}