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        try (BoxJSONResponse response = request.send()) {
084            JsonObject responseJSON = Json.parse(response.getJSON()).asObject();
085            BoxLegalHoldAssignment createdAssignment =
086                new BoxLegalHoldAssignment(api, responseJSON.get("id").asString());
087            return createdAssignment.new Info(responseJSON);
088        }
089    }
090
091    /**
092     * Deletes the legal hold policy assignment.
093     */
094    public void delete() {
095        URL url = LEGAL_HOLD_ASSIGNMENT_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID());
096        BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "DELETE");
097        request.send().close();
098    }
099
100    /**
101     * @param fields the fields to retrieve.
102     * @return information about this retention policy.
103     */
104    public BoxLegalHoldAssignment.Info getInfo(String... fields) {
105        QueryStringBuilder builder = new QueryStringBuilder();
106        if (fields.length > 0) {
107            builder.appendParam("fields", fields);
108        }
109        URL url = LEGAL_HOLD_ASSIGNMENT_URL_TEMPLATE.buildWithQuery(
110            this.getAPI().getBaseURL(), builder.toString(), this.getID());
111        BoxJSONRequest request = new BoxJSONRequest(this.getAPI(), url, "GET");
112        try (BoxJSONResponse response = request.send()) {
113            JsonObject responseJSON = Json.parse(response.getJSON()).asObject();
114            return new Info(responseJSON);
115        }
116    }
117
118    /**
119     * Contains information about the legal hold policy.
120     */
121    public class Info extends BoxResource.Info {
122
123        /**
124         * @see #getLegalHold()
125         */
126        private BoxLegalHoldPolicy.Info legalHold;
127
128        /**
129         * @see #getAssignedBy()
130         */
131        private BoxUser.Info assignedBy;
132
133        /**
134         * @see #getAssignedAt()
135         */
136        private Date assignedAt;
137
138        /**
139         * @see #getDeletedAt()
140         */
141        private Date deletedAt;
142
143        /**
144         * @see #getAssignedToType()
145         */
146        private String assignedToType;
147
148        /**
149         * @see #getAssignedToID()
150         */
151        private String assignedToID;
152
153        /**
154         * Constructs an empty Info object.
155         */
156        public Info() {
157            super();
158        }
159
160        /**
161         * Constructs an Info object by parsing information from a JSON string.
162         *
163         * @param json the JSON string to parse.
164         */
165        public Info(String json) {
166            super(json);
167        }
168
169        /**
170         * Constructs an Info object using an already parsed JSON object.
171         *
172         * @param jsonObject the parsed JSON object.
173         */
174        Info(JsonObject jsonObject) {
175            super(jsonObject);
176        }
177
178        /**
179         * {@inheritDoc}
180         */
181        @Override
182        public BoxResource getResource() {
183            return BoxLegalHoldAssignment.this;
184        }
185
186        /**
187         * @return info about the policy that this legal hold policy assignment is part of.
188         */
189        public BoxLegalHoldPolicy.Info getLegalHold() {
190            return this.legalHold;
191        }
192
193        /**
194         * @return the info about the user who created that legal hold policy assignment.
195         */
196        public BoxUser.Info getAssignedBy() {
197            return this.assignedBy;
198        }
199
200        /**
201         * @return the time that the legal hold policy assignment was created.
202         */
203        public Date getAssignedAt() {
204            return this.assignedAt;
205        }
206
207        /**
208         * @return the time that the assignment release request was sent.
209         */
210        public Date getDeletedAt() {
211            return this.deletedAt;
212        }
213
214        /**
215         * @return the entity type that this is assigned to.
216         */
217        public String getAssignedToType() {
218            return this.assignedToType;
219        }
220
221        /**
222         * @return the entity id that this is assigned to.
223         */
224        public String getAssignedToID() {
225            return this.assignedToID;
226        }
227
228        /**
229         * {@inheritDoc}
230         */
231        @Override
232        void parseJSONMember(JsonObject.Member member) {
233            super.parseJSONMember(member);
234            String memberName = member.getName();
235            JsonValue value = member.getValue();
236            try {
237                if (memberName.equals("legal_hold_policy")) {
238                    JsonObject policyJSON = value.asObject();
239                    if (this.legalHold == null) {
240                        String policyID = policyJSON.get("id").asString();
241                        BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(getAPI(), policyID);
242                        this.legalHold = policy.new Info(policyJSON);
243                    } else {
244                        this.legalHold.update(policyJSON);
245                    }
246                } else if (memberName.equals("assigned_to")) {
247                    JsonObject assignmentJSON = value.asObject();
248                    this.assignedToType = assignmentJSON.get("type").asString();
249                    this.assignedToID = assignmentJSON.get("id").asString();
250                } else if (memberName.equals("assigned_by")) {
251                    JsonObject userJSON = value.asObject();
252                    if (this.assignedBy == null) {
253                        String userID = userJSON.get("id").asString();
254                        BoxUser user = new BoxUser(getAPI(), userID);
255                        this.assignedBy = user.new Info(userJSON);
256                    } else {
257                        this.assignedBy.update(userJSON);
258                    }
259                } else if (memberName.equals("assigned_at")) {
260                    this.assignedAt = BoxDateFormat.parse(value.asString());
261                } else if (memberName.equals("deleted_at")) {
262                    this.deletedAt = BoxDateFormat.parse(value.asString());
263                }
264            } catch (Exception e) {
265                throw new BoxDeserializationException(memberName, value.toString(), e);
266            }
267        }
268    }
269}