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 file version retention.
011 * A retention policy blocks permanent deletion of content for a specified amount of time.
012 * Admins can apply policies to specified folders, or an entire enterprise.
013 * A file version retention is a record for a retained file version.
014 *
015 * @see <a href="https://developer.box.com/reference/resources/file-version-retention/">Box file version retention</a>
016 *
017 * <p>Unless otherwise noted, the methods in this class can throw an unchecked {@link BoxAPIException} (unchecked
018 * meaning that the compiler won't force you to handle it) if an error occurs. If you wish to implement custom error
019 * handling for errors related to the Box REST API, you should capture this exception explicitly.</p>
020 */
021@BoxResourceType("file_version_retention")
022public class BoxFileVersionRetention extends BoxResource {
023
024    /**
025     * @see #getInfo(String...)
026     */
027    public static final URLTemplate RETENTION_URL_TEMPLATE = new URLTemplate("file_version_retentions/%s");
028
029    /**
030     * The URL template used for operation with file version retentions.
031     */
032    public static final URLTemplate ALL_RETENTIONS_URL_TEMPLATE = new URLTemplate("file_version_retentions");
033
034    /**
035     * The default limit of entries per response.
036     */
037    private static final int DEFAULT_LIMIT = 100;
038
039    /**
040     * Constructs a BoxFileVersionRetention for a resource with a given ID.
041     *
042     * @param api the API connection to be used by the resource.
043     * @param id  the ID of the resource.
044     */
045    public BoxFileVersionRetention(BoxAPIConnection api, String id) {
046        super(api, id);
047    }
048
049    /**
050     * @param fields the fields to retrieve.
051     * @return information about this retention policy.
052     */
053    public BoxFileVersionRetention.Info getInfo(String ... fields) {
054        QueryStringBuilder builder = new QueryStringBuilder();
055        if (fields.length > 0) {
056            builder.appendParam("fields", fields);
057        }
058        URL url = RETENTION_URL_TEMPLATE.buildWithQuery(this.getAPI().getBaseURL(), builder.toString(), this.getID());
059        BoxAPIRequest request = new BoxAPIRequest(this.getAPI(), url, "GET");
060        BoxJSONResponse response = (BoxJSONResponse) request.send();
061        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
062        return new Info(responseJSON);
063    }
064
065    /**
066     * Retrieves all file version retentions.
067     * @param api the API connection to be used by the resource.
068     * @param fields the fields to retrieve.
069     * @return an iterable contains information about all file version retentions.
070     */
071    public static Iterable<BoxFileVersionRetention.Info> getAll(BoxAPIConnection api, String ... fields) {
072        return getRetentions(api, new QueryFilter(), fields);
073    }
074
075    /**
076     * @deprecated This method will be deprecated in the future. Please use
077     * BoxRetentionPolicyAssignment.getFilesUnderRetentionForAssignmentAsync(...)
078     * and BoxRetentionPolicyAssignment.getFileVersionsUnderRetentionForAssignmentAsync(...) instead."
079     * Retrieves all file version retentions matching given filters as an Iterable.
080     * @param api the API connection to be used by the resource.
081     * @param filter filters for the query stored in QueryFilter object.
082     * @param fields the fields to retrieve.
083     * @return an iterable contains information about all file version retentions matching given filter.
084     */
085    public static Iterable<BoxFileVersionRetention.Info> getRetentions(
086            final BoxAPIConnection api, QueryFilter filter, String ... fields) {
087        filter.addFields(fields);
088        return new BoxResourceIterable<BoxFileVersionRetention.Info>(api,
089                ALL_RETENTIONS_URL_TEMPLATE.buildWithQuery(api.getBaseURL(), filter.toString()),
090                DEFAULT_LIMIT) {
091
092            @Override
093            protected BoxFileVersionRetention.Info factory(JsonObject jsonObject) {
094                BoxFileVersionRetention retention = new BoxFileVersionRetention(api, jsonObject.get("id").asString());
095                return retention.new Info(jsonObject);
096            }
097        };
098    }
099
100    /**
101     * Contains information about the retention policy.
102     */
103    public class Info extends BoxResource.Info {
104
105        /**
106         * @see #getFileVersion()
107         */
108        private BoxFileVersion fileVersion;
109
110        /**
111         * @see #getFile()
112         */
113        private BoxFile.Info file;
114
115        /**
116         * @see #getAppliedAt()
117         */
118        private Date appliedAt;
119
120        /**
121         * @see #getDispositionAt()
122         */
123        private Date dispositionAt;
124
125        /**
126         * @see #getWinningPolicy()
127         */
128        private BoxRetentionPolicy.Info winningPolicy;
129
130        /**
131         * Constructs an empty Info object.
132         */
133        public Info() {
134            super();
135        }
136
137        /**
138         * Constructs an Info object by parsing information from a JSON string.
139         * @param  json the JSON string to parse.
140         */
141        public Info(String json) {
142            super(json);
143        }
144
145        /**
146         * Constructs an Info object using an already parsed JSON object.
147         * @param  jsonObject the parsed JSON object.
148         */
149        Info(JsonObject jsonObject) {
150            super(jsonObject);
151        }
152
153        /**
154         * {@inheritDoc}
155         */
156        @Override
157        public BoxResource getResource() {
158            return BoxFileVersionRetention.this;
159        }
160
161        /**
162         * @return the file version this file version retention was applied to.
163         */
164        public BoxFileVersion getFileVersion() {
165            return this.fileVersion;
166        }
167
168        /**
169         * @return the file this file version retention was applied to.
170         */
171        public BoxFile.Info getFile() {
172            return this.file;
173        }
174
175        /**
176         * @return the time that this file version retention was created.
177         */
178        public Date getAppliedAt() {
179            return this.appliedAt;
180        }
181
182        /**
183         * @return the time that the retention period expires on this file version retention.
184         */
185        public Date getDispositionAt() {
186            return this.dispositionAt;
187        }
188
189        /**
190         * @return the winning retention policy applied to this file version retention.
191         */
192        public BoxRetentionPolicy.Info getWinningPolicy() {
193            return this.winningPolicy;
194        }
195
196        /**
197         * {@inheritDoc}
198         */
199        @Override
200        void parseJSONMember(JsonObject.Member member) {
201            super.parseJSONMember(member);
202            String memberName = member.getName();
203            JsonValue value = member.getValue();
204            try {
205                if (memberName.equals("winning_retention_policy")) {
206                    JsonObject policyJSON = value.asObject();
207                    if (this.winningPolicy == null) {
208                        String policyID = policyJSON.get("id").asString();
209                        BoxRetentionPolicy policy = new BoxRetentionPolicy(getAPI(), policyID);
210                        this.winningPolicy = policy.new Info(policyJSON);
211                    } else {
212                        this.winningPolicy.update(policyJSON);
213                    }
214                } else if (memberName.equals("file")) {
215                    JsonObject fileJSON = value.asObject();
216                    if (this.file == null) {
217                        String fileID = fileJSON.get("id").asString();
218                        BoxFile file = new BoxFile(getAPI(), fileID);
219                        this.file = file.new Info(fileJSON);
220                    } else {
221                        this.file.update(fileJSON);
222                    }
223                } else if (memberName.equals("file_version")) {
224                    JsonObject versionJSON = value.asObject();
225                    String fileVersionID = versionJSON.get("id").asString();
226                    this.fileVersion = new BoxFileVersion(getAPI(), versionJSON, fileVersionID);
227                } else if (memberName.equals("applied_at")) {
228                    this.appliedAt = BoxDateFormat.parse(value.asString());
229                } else if (memberName.equals("disposition_at")) {
230                    this.dispositionAt = BoxDateFormat.parse(value.asString());
231                }
232            } catch (Exception e) {
233                throw new BoxDeserializationException(memberName, value.toString(), e);
234            }
235        }
236    }
237
238    /**
239     * Represents possible query filters for "Get File Version Retentions" function.
240     */
241    public static class QueryFilter extends QueryStringBuilder {
242
243        /**
244         * Param name for the file id to filter the file version retentions by.
245         */
246        private static final String PARAM_FILE_ID = "file_id";
247
248        /**
249         * Param name for the file version id to filter the file version retentions by.
250         */
251        private static final String PARAM_FILE_VERSION_ID = "file_version_id";
252
253        /**
254         * Param name for the policy id to filter the file version retentions by.
255         */
256        private static final String PARAM_POLICY_ID = "policy_id";
257
258        /**
259         * Param name for the disposition action of the retention policy.
260         */
261        private static final String PARAM_DISPOSITION_ACTION = "disposition_action";
262
263        /**
264         * Param name for the datetime to filter file version retentions.
265         */
266        private static final String PARAM_DISPOSITION_BEFORE = "disposition_before";
267
268        /**
269         * Param name for the datetime to filter file version retentions.
270         */
271        private static final String PARAM_DISPOSITION_AFTER = "disposition_after";
272
273        /**
274         * Param name for the the fields to retrieve.
275         */
276        private static final String PARAM_FIELDS = "fields";
277
278        /**
279         * Constructs empty query filter.
280         */
281        public QueryFilter() {
282            super();
283        }
284
285        /**
286         * @param id a file id to filter the file version retentions by.
287         * @return modified query filter.
288         */
289        public QueryFilter addFileID(String id) {
290            this.appendParam(PARAM_FILE_ID, id);
291            return this;
292        }
293
294        /**
295         * @param id a file version id to filter the file version retentions by.
296         * @return modified query filter.
297         */
298        public QueryFilter addFileVersionID(String id) {
299            this.appendParam(PARAM_FILE_VERSION_ID, id);
300            return this;
301        }
302
303        /**
304         * @param id a policy id to filter the file version retentions by.
305         * @return modified query filter.
306         */
307        public QueryFilter addPolicyID(String id) {
308            this.appendParam(PARAM_POLICY_ID, id);
309            return this;
310        }
311
312        /**
313         * The action can be "permanently_delete" or "remove_retention".
314         * @param action the disposition action of the retention policy.
315         * @return modified query filter.
316         */
317        public QueryFilter addDispositionAction(String action) {
318            this.appendParam(PARAM_DISPOSITION_ACTION, action);
319            return this;
320        }
321
322        /**
323         * @param date the datetime to filter file version retentions.
324         * @return modified query filter.
325         */
326        public QueryFilter addDispositionBefore(Date date) {
327            this.appendParam(PARAM_DISPOSITION_BEFORE, BoxDateFormat.format(date));
328            return this;
329        }
330
331        /**
332         * @param date the datetime to filter file version retentions.
333         * @return modified query filter.
334         */
335        public QueryFilter addDispositionAfter(Date date) {
336            this.appendParam(PARAM_DISPOSITION_AFTER, BoxDateFormat.format(date));
337            return this;
338        }
339
340        /**
341         * @param fields the fields to retrieve.
342         * @return modified query filter.
343         */
344        public QueryFilter addFields(String ... fields) {
345            if (fields.length > 0) {
346                this.appendParam(PARAM_FIELDS, fields);
347            }
348            return this;
349        }
350    }
351}