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 legal hold policy assignment.
011 * Legal hold assignments are used to assign legal hold policies to custodians, folders, files, or file versions.
012 *
013 * @see <a href="https://developer.box.com/reference/resources/legal-hold-policy-assignment/">Box legal holds</a>
014 *
015 * <p>Unless otherwise noted, the methods in this class can throw an unchecked {@link BoxAPIException} (unchecked
016 * meaning that the compiler won't force you to handle it) if an error occurs. If you wish to implement custom error
017 * handling for errors related to the Box REST API, you should capture this exception explicitly.</p>
018 */
019@BoxResourceType("legal_hold_assignment")
020public class BoxLegalHoldAssignment extends BoxResource {
021
022    /**
023     * Used to assign legal hold policy to file version.
024     */
025    public static final String TYPE_FILE_VERSION = BoxFileVersion.getResourceType(BoxFileVersion.class);
026
027    /**
028     * Used to assign legal hold policy to file.
029     */
030    public static final String TYPE_FILE = BoxFile.getResourceType(BoxFile.class);
031
032    /**
033     * Used to assign legal hold policy to folder.
034     */
035    public static final String TYPE_FOLDER = BoxFolder.getResourceType(BoxFolder.class);
036
037    /**
038     * Used to assign legal hold policy to user.
039     */
040    public static final String TYPE_USER = BoxUser.getResourceType(BoxUser.class);
041
042    /**
043     * The URL template used for operation with legal hold policy assignments.
044     */
045    public static final URLTemplate ASSIGNMENTS_URL_TEMPLATE = new URLTemplate("legal_hold_policy_assignments");
046
047    /**
048     * The URL template used for operation with legal hold policy assignment with given ID.
049     */
050    public static final URLTemplate LEGAL_HOLD_ASSIGNMENT_URL_TEMPLATE
051        = new URLTemplate("legal_hold_policy_assignments/%s");
052
053    /**
054     * Constructs a BoxLegalHoldAssignment for a resource with a given ID.
055     *
056     * @param api the API connection to be used by the resource.
057     * @param id  the ID of the resource.
058     */
059    public BoxLegalHoldAssignment(BoxAPIConnection api, String id) {
060        super(api, id);
061    }
062
063    /**
064     * Creates new legal hold policy assignment.
065     *
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 = Json.parse(response.getJSON()).asObject();
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 = Json.parse(response.getJSON()).asObject();
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         *
161         * @param json the JSON string to parse.
162         */
163        public Info(String json) {
164            super(json);
165        }
166
167        /**
168         * Constructs an Info object using an already parsed JSON object.
169         *
170         * @param jsonObject the parsed JSON object.
171         */
172        Info(JsonObject jsonObject) {
173            super(jsonObject);
174        }
175
176        /**
177         * {@inheritDoc}
178         */
179        @Override
180        public BoxResource getResource() {
181            return BoxLegalHoldAssignment.this;
182        }
183
184        /**
185         * @return info about the policy that this legal hold policy assignment is part of.
186         */
187        public BoxLegalHoldPolicy.Info getLegalHold() {
188            return this.legalHold;
189        }
190
191        /**
192         * @return the info about the user who created that legal hold policy assignment.
193         */
194        public BoxUser.Info getAssignedBy() {
195            return this.assignedBy;
196        }
197
198        /**
199         * @return the time that the legal hold policy assignment was created.
200         */
201        public Date getAssignedAt() {
202            return this.assignedAt;
203        }
204
205        /**
206         * @return the time that the assignment release request was sent.
207         */
208        public Date getDeletedAt() {
209            return this.deletedAt;
210        }
211
212        /**
213         * @return the entity type that this is assigned to.
214         */
215        public String getAssignedToType() {
216            return this.assignedToType;
217        }
218
219        /**
220         * @return the entity id that this is assigned to.
221         */
222        public String getAssignedToID() {
223            return this.assignedToID;
224        }
225
226        /**
227         * {@inheritDoc}
228         */
229        @Override
230        void parseJSONMember(JsonObject.Member member) {
231            super.parseJSONMember(member);
232            String memberName = member.getName();
233            JsonValue value = member.getValue();
234            try {
235                if (memberName.equals("legal_hold_policy")) {
236                    JsonObject policyJSON = value.asObject();
237                    if (this.legalHold == null) {
238                        String policyID = policyJSON.get("id").asString();
239                        BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(getAPI(), policyID);
240                        this.legalHold = policy.new Info(policyJSON);
241                    } else {
242                        this.legalHold.update(policyJSON);
243                    }
244                } else if (memberName.equals("assigned_to")) {
245                    JsonObject assignmentJSON = value.asObject();
246                    this.assignedToType = assignmentJSON.get("type").asString();
247                    this.assignedToID = assignmentJSON.get("id").asString();
248                } else if (memberName.equals("assigned_by")) {
249                    JsonObject userJSON = value.asObject();
250                    if (this.assignedBy == null) {
251                        String userID = userJSON.get("id").asString();
252                        BoxUser user = new BoxUser(getAPI(), userID);
253                        this.assignedBy = user.new Info(userJSON);
254                    } else {
255                        this.assignedBy.update(userJSON);
256                    }
257                } else if (memberName.equals("assigned_at")) {
258                    this.assignedAt = BoxDateFormat.parse(value.asString());
259                } else if (memberName.equals("deleted_at")) {
260                    this.deletedAt = BoxDateFormat.parse(value.asString());
261                }
262            } catch (Exception e) {
263                throw new BoxDeserializationException(memberName, value.toString(), e);
264            }
265        }
266    }
267}