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