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