001package com.box.sdk;
002
003import java.net.URL;
004import java.util.Date;
005
006import com.eclipsesource.json.JsonObject;
007import com.eclipsesource.json.JsonValue;
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://docs.box.com/reference#legal-holds-assignment-object">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     * @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         * @param  json the JSON string to parse.
160         */
161        public Info(String json) {
162            super(json);
163        }
164
165        /**
166         * Constructs an Info object using an already parsed JSON object.
167         * @param  jsonObject the parsed JSON object.
168         */
169        Info(JsonObject jsonObject) {
170            super(jsonObject);
171        }
172
173        /**
174         * {@inheritDoc}
175         */
176        @Override
177        public BoxResource getResource() {
178            return BoxLegalHoldAssignment.this;
179        }
180
181        /**
182         * @return info about the policy that this legal hold policy assignment is part of.
183         */
184        public BoxLegalHoldPolicy.Info getLegalHold() {
185            return this.legalHold;
186        }
187
188        /**
189         * @return the info about the user who created that legal hold policy assignment.
190         */
191        public BoxUser.Info getAssignedBy() {
192            return this.assignedBy;
193        }
194
195        /**
196         * @return the time that the legal hold policy assignment was created.
197         */
198        public Date getAssignedAt() {
199            return this.assignedAt;
200        }
201
202        /**
203         * @return the time that the assignment release request was sent.
204         */
205        public Date getDeletedAt() {
206            return this.deletedAt;
207        }
208
209        /**
210         * @return the entity type that this is assigned to.
211         */
212        public String getAssignedToType() {
213            return this.assignedToType;
214        }
215
216        /**
217         * @return the entity id that this is assigned to.
218         */
219        public String getAssignedToID() {
220            return this.assignedToID;
221        }
222
223        /**
224         * {@inheritDoc}
225         */
226        @Override
227        void parseJSONMember(JsonObject.Member member) {
228            super.parseJSONMember(member);
229            String memberName = member.getName();
230            JsonValue value = member.getValue();
231            try {
232                if (memberName.equals("legal_hold_policy")) {
233                    JsonObject policyJSON = value.asObject();
234                    if (this.legalHold == null) {
235                        String policyID = policyJSON.get("id").asString();
236                        BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(getAPI(), policyID);
237                        this.legalHold = policy.new Info(policyJSON);
238                    } else {
239                        this.legalHold.update(policyJSON);
240                    }
241                } else if (memberName.equals("assigned_to")) {
242                    JsonObject assignmentJSON = value.asObject();
243                    this.assignedToType = assignmentJSON.get("type").asString();
244                    this.assignedToID = assignmentJSON.get("id").asString();
245                } else if (memberName.equals("assigned_by")) {
246                    JsonObject userJSON = value.asObject();
247                    if (this.assignedBy == null) {
248                        String userID = userJSON.get("id").asString();
249                        BoxUser user = new BoxUser(getAPI(), userID);
250                        this.assignedBy = user.new Info(userJSON);
251                    } else {
252                        this.assignedBy.update(userJSON);
253                    }
254                } else if (memberName.equals("assigned_at")) {
255                    this.assignedAt = BoxDateFormat.parse(value.asString());
256                } else if (memberName.equals("deleted_at")) {
257                    this.deletedAt = BoxDateFormat.parse(value.asString());
258                }
259            } catch (Exception e) {
260                throw new BoxDeserializationException(memberName, value.toString(), e);
261            }
262        }
263    }
264}