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