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 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 user that assigned the assignment.
193         * @return the user that assigned the assignment.
194         */
195        public BoxUser.Info getAssignedBy() {
196            return this.assignedBy;
197        }
198
199        @Override
200        void parseJSONMember(JsonObject.Member member) {
201            super.parseJSONMember(member);
202
203            String memberName = member.getName();
204            JsonValue value = member.getValue();
205            try {
206                if (memberName.equals("item")) {
207                    JsonObject itemJSON = value.asObject();
208                    String itemID = itemJSON.get("id").asString();
209                    BoxFile file = new BoxFile(getAPI(), itemID);
210                    this.item = file.new Info(itemJSON);
211                } else if (memberName.equals("assigned_to")) {
212                    JsonObject userJSON = value.asObject();
213                    String userID = userJSON.get("id").asString();
214                    BoxUser user = new BoxUser(getAPI(), userID);
215                    this.assignedTo = user.new Info(userJSON);
216                } else if (memberName.equals("message")) {
217                    this.message = value.asString();
218                } else if (memberName.equals("completed_at")) {
219                    this.completedAt = BoxDateFormat.parse(value.asString());
220                } else if (memberName.equals("assigned_at")) {
221                    this.assignedAt = BoxDateFormat.parse(value.asString());
222                } else if (memberName.equals("reminded_at")) {
223                    this.remindedAt = BoxDateFormat.parse(value.asString());
224                } else if (memberName.equals("resolution_state")) {
225                    this.resolutionState = ResolutionState.fromJSONString(value.asString());
226                } else if (memberName.equals("assigned_by")) {
227                    JsonObject userJSON = value.asObject();
228                    String userID = userJSON.get("id").asString();
229                    BoxUser user = new BoxUser(getAPI(), userID);
230                    this.assignedBy = user.new Info(userJSON);
231                }
232            } catch (ParseException e) {
233                assert false : "A ParseException indicates a bug in the SDK.";
234            }
235        }
236    }
237
238    /**
239     * Enumerates the possible resolution states that a task assignment can have.
240     */
241    public enum ResolutionState {
242        /**
243         * The task assignment has been completed.
244         */
245        COMPLETED ("completed"),
246
247        /**
248         * The task assignment is incomplete.
249         */
250        INCOMPLETE ("incomplete"),
251
252        /**
253         * The task assignment has been approved.
254         */
255        APPROVED ("approved"),
256
257        /**
258         * The task assignment has been rejected.
259         */
260        REJECTED ("rejected");
261
262        private final String jsonValue;
263
264        private ResolutionState(String jsonValue) {
265            this.jsonValue = jsonValue;
266        }
267
268        static ResolutionState fromJSONString(String jsonValue) {
269            if (jsonValue.equals("completed")) {
270                return COMPLETED;
271            } else if (jsonValue.equals("incomplete")) {
272                return INCOMPLETE;
273            } else if (jsonValue.equals("approved")) {
274                return APPROVED;
275            } else if (jsonValue.equals("rejected")) {
276                return REJECTED;
277            } else {
278                throw new IllegalArgumentException("The provided JSON value isn't a valid ResolutionState.");
279            }
280        }
281
282        String toJSONString() {
283            return this.jsonValue;
284        }
285    }
286}