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 legal hold policy assignment.
012 * Legal hold assignments are used to assign legal hold policies to custodians, folders, files, or file versions.
013 *
014 * @see <a href="https://docs.box.com/reference#legal-holds-assignment-object">Box legal holds</a>
015 *
016 * <p>Unless otherwise noted, the methods in this class can throw an unchecked {@link BoxAPIException} (unchecked
017 * meaning that the compiler won't force you to handle it) if an error occurs. If you wish to implement custom error
018 * handling for errors related to the Box REST API, you should capture this exception explicitly.</p>
019 */
020@BoxResourceType("legal_hold_assignment")
021public class BoxLegalHoldAssignment extends BoxResource {
022
023    /**
024     * Used to assign legal hold policy to file version.
025     */
026    public static final String TYPE_FILE_VERSION = BoxFileVersion.getResourceType(BoxFileVersion.class);
027
028    /**
029     * Used to assign legal hold policy to file.
030     */
031    public static final String TYPE_FILE = BoxFile.getResourceType(BoxFile.class);
032
033    /**
034     * Used to assign legal hold policy to folder.
035     */
036    public static final String TYPE_FOLDER = BoxFolder.getResourceType(BoxFolder.class);
037
038    /**
039     * Used to assign legal hold policy to user.
040     */
041    public static final String TYPE_USER = BoxUser.getResourceType(BoxUser.class);
042
043    /**
044     * The URL template used for operation with legal hold policy assignments.
045     */
046    public static final URLTemplate ASSIGNMENTS_URL_TEMPLATE = new URLTemplate("legal_hold_policy_assignments");
047
048    /**
049     * The URL template used for operation with legal hold policy assignment with given ID.
050     */
051    public static final URLTemplate LEGAL_HOLD_ASSIGNMENT_URL_TEMPLATE
052        = new URLTemplate("legal_hold_policy_assignments/%s");
053
054    /**
055     * Constructs a BoxLegalHoldAssignment for a resource with a given ID.
056     *
057     * @param api the API connection to be used by the resource.
058     * @param id  the ID of the resource.
059     */
060    public BoxLegalHoldAssignment(BoxAPIConnection api, String id) {
061        super(api, id);
062    }
063
064    /**
065     * Creates new legal hold policy assignment.
066     * @param api the API connection to be used by the resource.
067     * @param policyID ID of policy to create assignment for.
068     * @param resourceType type of target resource. Can be 'file_version', 'file', 'folder', or 'user'.
069     * @param resourceID ID of the target resource.
070     * @return info about created legal hold policy assignment.
071     */
072    public static BoxLegalHoldAssignment.Info create(BoxAPIConnection api,
073                                                     String policyID, String resourceType, String resourceID) {
074        URL url = ASSIGNMENTS_URL_TEMPLATE.build(api.getBaseURL());
075        BoxJSONRequest request = new BoxJSONRequest(api, url, "POST");
076
077        JsonObject requestJSON = new JsonObject()
078                .add("policy_id", policyID)
079                .add("assign_to", new JsonObject()
080                        .add("type", resourceType)
081                        .add("id", resourceID));
082        request.setBody(requestJSON.toString());
083        BoxJSONResponse response = (BoxJSONResponse) request.send();
084        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
085        BoxLegalHoldAssignment createdAssignment = new BoxLegalHoldAssignment(api, responseJSON.get("id").asString());
086        return createdAssignment.new Info(responseJSON);
087    }
088
089    /**
090     * Deletes the legal hold policy assignment.
091     */
092    public void delete() {
093        URL url = LEGAL_HOLD_ASSIGNMENT_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID());
094        BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "DELETE");
095        BoxAPIResponse response = request.send();
096        response.disconnect();
097    }
098
099    /**
100     * @param fields the fields to retrieve.
101     * @return information about this retention policy.
102     */
103    public BoxLegalHoldAssignment.Info getInfo(String ... fields) {
104        QueryStringBuilder builder = new QueryStringBuilder();
105        if (fields.length > 0) {
106            builder.appendParam("fields", fields);
107        }
108        URL url = LEGAL_HOLD_ASSIGNMENT_URL_TEMPLATE.buildWithQuery(
109                this.getAPI().getBaseURL(), builder.toString(), this.getID());
110        BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "GET");
111        BoxJSONResponse response = (BoxJSONResponse) request.send();
112        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
113        return new Info(responseJSON);
114    }
115
116    /**
117     * Contains information about the legal hold policy.
118     */
119    public class Info extends BoxResource.Info {
120
121        /**
122         * @see #getLegalHold()
123         */
124        private BoxLegalHoldPolicy.Info legalHold;
125
126        /**
127         * @see #getAssignedBy()
128         */
129        private BoxUser.Info assignedBy;
130
131        /**
132         * @see #getAssignedAt()
133         */
134        private Date assignedAt;
135
136        /**
137         * @see #getDeletedAt()
138         */
139        private Date deletedAt;
140
141        /**
142         * @see #getAssignedToType()
143         */
144        private String assignedToType;
145
146        /**
147         * @see #getAssignedToID()
148         */
149        private String assignedToID;
150
151        /**
152         * Constructs an empty Info object.
153         */
154        public Info() {
155            super();
156        }
157
158        /**
159         * Constructs an Info object by parsing information from a JSON string.
160         * @param  json the JSON string to parse.
161         */
162        public Info(String json) {
163            super(json);
164        }
165
166        /**
167         * Constructs an Info object using an already parsed JSON object.
168         * @param  jsonObject the parsed JSON object.
169         */
170        Info(JsonObject jsonObject) {
171            super(jsonObject);
172        }
173
174        /**
175         * {@inheritDoc}
176         */
177        @Override
178        public BoxResource getResource() {
179            return BoxLegalHoldAssignment.this;
180        }
181
182        /**
183         * @return info about the policy that this legal hold policy assignment is part of.
184         */
185        public BoxLegalHoldPolicy.Info getLegalHold() {
186            return this.legalHold;
187        }
188
189        /**
190         * @return the info about the user who created that legal hold policy assignment.
191         */
192        public BoxUser.Info getAssignedBy() {
193            return this.assignedBy;
194        }
195
196        /**
197         * @return the time that the legal hold policy assignment was created.
198         */
199        public Date getAssignedAt() {
200            return this.assignedAt;
201        }
202
203        /**
204         * @return the time that the assignment release request was sent.
205         */
206        public Date getDeletedAt() {
207            return this.deletedAt;
208        }
209
210        /**
211         * @return the entity type that this is assigned to.
212         */
213        public String getAssignedToType() {
214            return this.assignedToType;
215        }
216
217        /**
218         * @return the entity id that this is assigned to.
219         */
220        public String getAssignedToID() {
221            return this.assignedToID;
222        }
223
224        /**
225         * {@inheritDoc}
226         */
227        @Override
228        void parseJSONMember(JsonObject.Member member) {
229            super.parseJSONMember(member);
230            String memberName = member.getName();
231            JsonValue value = member.getValue();
232            try {
233                if (memberName.equals("legal_hold_policy")) {
234                    JsonObject policyJSON = value.asObject();
235                    if (this.legalHold == null) {
236                        String policyID = policyJSON.get("id").asString();
237                        BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(getAPI(), policyID);
238                        this.legalHold = policy.new Info(policyJSON);
239                    } else {
240                        this.legalHold.update(policyJSON);
241                    }
242                } else if (memberName.equals("assigned_to")) {
243                    JsonObject assignmentJSON = value.asObject();
244                    this.assignedToType = assignmentJSON.get("type").asString();
245                    this.assignedToID = assignmentJSON.get("id").asString();
246                } else if (memberName.equals("assigned_by")) {
247                    JsonObject userJSON = value.asObject();
248                    if (this.assignedBy == null) {
249                        String userID = userJSON.get("id").asString();
250                        BoxUser user = new BoxUser(getAPI(), userID);
251                        this.assignedBy = user.new Info(userJSON);
252                    } else {
253                        this.assignedBy.update(userJSON);
254                    }
255                } else if (memberName.equals("assigned_at")) {
256                    this.assignedAt = BoxDateFormat.parse(value.asString());
257                } else if (memberName.equals("deleted_at")) {
258                    this.deletedAt = BoxDateFormat.parse(value.asString());
259                }
260            } catch (ParseException e) {
261                assert false : "A ParseException indicates a bug in the SDK.";
262            }
263        }
264    }
265}