001package com.box.sdk;
002
003import com.eclipsesource.json.JsonObject;
004import com.eclipsesource.json.JsonValue;
005import java.net.URL;
006import java.util.Date;
007
008/**
009 * Represents a task assignment on Box, which can be used to assign a task to a single user. There can be multiple
010 * assignments on a single task.
011 */
012@BoxResourceType("task_assignment")
013public class BoxTaskAssignment extends BoxResource {
014
015    /**
016     * Task Assignment URL Template.
017     */
018    public static final URLTemplate TASK_ASSIGNMENT_URL_TEMPLATE = new URLTemplate("task_assignments/%s");
019
020    /**
021     * Constructs a BoxTaskAssignment for a task assignment with a given ID.
022     *
023     * @param api the API connection to be used by the resource.
024     * @param id  the ID of the task assignment.
025     */
026    public BoxTaskAssignment(BoxAPIConnection api, String id) {
027        super(api, id);
028    }
029
030    /**
031     * Deletes this task assignment.
032     */
033    public void delete() {
034        URL url = TASK_ASSIGNMENT_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID());
035        BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "DELETE");
036        BoxAPIResponse response = request.send();
037        response.disconnect();
038    }
039
040    /**
041     * Gets information about this task assignment.
042     *
043     * @return info about this task assignment.
044     */
045    public Info getInfo() {
046        URL url = TASK_ASSIGNMENT_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID());
047        BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "GET");
048        BoxJSONResponse response = (BoxJSONResponse) request.send();
049        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
050        return new Info(responseJSON);
051    }
052
053    /**
054     * Gets information about this task assignment.
055     *
056     * @param fields the fields to retrieve.
057     * @return info about this task assignment.
058     */
059    public Info getInfo(String... fields) {
060        QueryStringBuilder builder = new QueryStringBuilder();
061        if (fields.length > 0) {
062            builder.appendParam("fields", fields);
063        }
064        URL url = TASK_ASSIGNMENT_URL_TEMPLATE.buildWithQuery(
065            this.getAPI().getBaseURL(), builder.toString(), this.getID());
066        BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "GET");
067        BoxJSONResponse response = (BoxJSONResponse) request.send();
068        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
069        return new Info(responseJSON);
070    }
071
072    /**
073     * Updates the information about this task assignment with any info fields that have been modified locally.
074     *
075     * <p>The only fields that will be updated are the ones that have been modified locally. For example, the following
076     * code won't update any information (or even send a network request) since none of the info's fields were
077     * changed:</p>
078     *
079     * <pre>BoxTaskAssignment taskAssignment = new BoxTaskAssignment(api, id);
080     * BoxTaskAssignment.Info info = taskAssignment.getInfo();
081     * taskAssignment.updateInfo(info);</pre>
082     *
083     * @param info the updated info.
084     */
085    public void updateInfo(BoxTaskAssignment.Info info) {
086        URL url = TASK_ASSIGNMENT_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID());
087        BoxJSONRequest request = new BoxJSONRequest(this.getAPI(), url, "PUT");
088        request.setBody(info.getPendingChanges());
089        BoxJSONResponse response = (BoxJSONResponse) request.send();
090        JsonObject jsonObject = JsonObject.readFrom(response.getJSON());
091        info.update(jsonObject);
092    }
093
094    /**
095     * Enumerates the possible resolution states that a task assignment can have.
096     */
097    public enum ResolutionState {
098        /**
099         * The task assignment has been completed.
100         */
101        COMPLETED("completed"),
102
103        /**
104         * The task assignment is incomplete.
105         */
106        INCOMPLETE("incomplete"),
107
108        /**
109         * The task assignment has been approved.
110         */
111        APPROVED("approved"),
112
113        /**
114         * The task assignment has been rejected.
115         */
116        REJECTED("rejected");
117
118        private final String jsonValue;
119
120        ResolutionState(String jsonValue) {
121            this.jsonValue = jsonValue;
122        }
123
124        static ResolutionState fromJSONString(String jsonValue) {
125            if (jsonValue.equals("completed")) {
126                return COMPLETED;
127            } else if (jsonValue.equals("incomplete")) {
128                return INCOMPLETE;
129            } else if (jsonValue.equals("approved")) {
130                return APPROVED;
131            } else if (jsonValue.equals("rejected")) {
132                return REJECTED;
133            } else {
134                throw new IllegalArgumentException("The provided JSON value isn't a valid ResolutionState.");
135            }
136        }
137
138        String toJSONString() {
139            return this.jsonValue;
140        }
141    }
142
143    /**
144     * Contains information about a task assignment.
145     */
146    public class Info extends BoxResource.Info {
147        private BoxItem.Info item;
148        private BoxUser.Info assignedTo;
149        private String message;
150        private Date completedAt;
151        private Date assignedAt;
152        private Date remindedAt;
153        private ResolutionState resolutionState;
154        private String status;
155        private BoxUser.Info assignedBy;
156
157        /**
158         * Constructs an empty Info object.
159         */
160        public Info() {
161            super();
162        }
163
164        /**
165         * Constructs an Info object by parsing information from a JSON string.
166         *
167         * @param json the JSON string to parse.
168         */
169        public Info(String json) {
170            super(json);
171        }
172
173        /**
174         * Constructs an Info object using an already parsed JSON object.
175         *
176         * @param jsonObject the parsed JSON object.
177         */
178        Info(JsonObject jsonObject) {
179            super(jsonObject);
180        }
181
182        @Override
183        public BoxResource getResource() {
184            return BoxTaskAssignment.this;
185        }
186
187        /**
188         * Gets the item associated with this task.
189         *
190         * @return the item associated with this task.
191         */
192        public BoxItem.Info getItem() {
193            return this.item;
194        }
195
196        /**
197         * Gets the user the assignment is assigned to.
198         *
199         * @return the user assigned to this assignment.
200         */
201        public BoxUser.Info getAssignedTo() {
202            return this.assignedTo;
203        }
204
205        /**
206         * Gets the message that will be included with this task assignment.
207         *
208         * @return the message that will be included with this task assignment.
209         */
210        public String getMessage() {
211            return this.message;
212        }
213
214        /**
215         * Sets the message for the assignment.
216         *
217         * @param message the message to be set on the assignment.
218         */
219        public void setMessage(String message) {
220            this.message = message;
221            this.addPendingChange("message", message);
222        }
223
224        /**
225         * Gets the date the assignment is to be completed at.
226         *
227         * @return the date the assignment is to be completed at.
228         */
229        public Date getCompletedAt() {
230            return this.completedAt;
231        }
232
233        /**
234         * Gets the date the assignment was assigned at.
235         *
236         * @return the date the assignment was assigned at.
237         */
238        public Date getAssignedAt() {
239            return this.assignedAt;
240        }
241
242        /**
243         * Gets the date the assignee is to be reminded at.
244         *
245         * @return the date the assignee is to be reminded at.
246         */
247        public Date getRemindedAt() {
248            return this.remindedAt;
249        }
250
251        /**
252         * Gets the current resolution state of the assignment.
253         *
254         * @return the current resolution state of the assignment.
255         */
256        public ResolutionState getResolutionState() {
257            return this.resolutionState;
258        }
259
260        /**
261         * Sets the resolution state for the assignment.
262         *
263         * @param resolutionState the resolution state to be set on the assignment.
264         */
265        public void setResolutionState(ResolutionState resolutionState) {
266            this.resolutionState = resolutionState;
267            this.addPendingChange("resolution_state", resolutionState.toJSONString());
268        }
269
270        /**
271         * Gets the current status of the assignment.
272         *
273         * @return the current status of the assignment.
274         */
275        public String getStatus() {
276            return this.status;
277        }
278
279        /**
280         * Sets the status for the assignment.
281         *
282         * @param status the status to be set on the assignment.
283         */
284        public void setStatus(String status) {
285            this.status = status;
286            this.addPendingChange("status", status);
287        }
288
289        /**
290         * Gets the user that assigned the assignment.
291         *
292         * @return the user that assigned the assignment.
293         */
294        public BoxUser.Info getAssignedBy() {
295            return this.assignedBy;
296        }
297
298        @Override
299        void parseJSONMember(JsonObject.Member member) {
300            super.parseJSONMember(member);
301
302            String memberName = member.getName();
303            JsonValue value = member.getValue();
304            try {
305                if (memberName.equals("item")) {
306                    JsonObject itemJSON = value.asObject();
307                    String itemID = itemJSON.get("id").asString();
308                    BoxFile file = new BoxFile(getAPI(), itemID);
309                    this.item = file.new Info(itemJSON);
310                } else if (memberName.equals("assigned_to")) {
311                    JsonObject userJSON = value.asObject();
312                    String userID = userJSON.get("id").asString();
313                    BoxUser user = new BoxUser(getAPI(), userID);
314                    this.assignedTo = user.new Info(userJSON);
315                } else if (memberName.equals("message")) {
316                    this.message = value.asString();
317                } else if (memberName.equals("completed_at")) {
318                    this.completedAt = BoxDateFormat.parse(value.asString());
319                } else if (memberName.equals("assigned_at")) {
320                    this.assignedAt = BoxDateFormat.parse(value.asString());
321                } else if (memberName.equals("reminded_at")) {
322                    this.remindedAt = BoxDateFormat.parse(value.asString());
323                } else if (memberName.equals("resolution_state")) {
324                    this.resolutionState = ResolutionState.fromJSONString(value.asString());
325                } else if (memberName.equals("status")) {
326                    this.status = value.asString();
327                } else if (memberName.equals("assigned_by")) {
328                    JsonObject userJSON = value.asObject();
329                    String userID = userJSON.get("id").asString();
330                    BoxUser user = new BoxUser(getAPI(), userID);
331                    this.assignedBy = user.new Info(userJSON);
332                }
333            } catch (Exception e) {
334                throw new BoxDeserializationException(memberName, value.toString(), e);
335            }
336        }
337    }
338}