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}