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