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