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