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 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     * Retrieves all file version retentions.
051     *
052     * @param api    the API connection to be used by the resource.
053     * @param fields the fields to retrieve.
054     * @return an iterable contains information about all file version retentions.
055     */
056    public static Iterable<BoxFileVersionRetention.Info> getAll(BoxAPIConnection api, String... fields) {
057        return getRetentions(api, new QueryFilter(), fields);
058    }
059
060    /**
061     * Retrieves all file version retentions matching given filters as an Iterable.
062     *
063     * @param api    the API connection to be used by the resource.
064     * @param filter filters for the query stored in QueryFilter object.
065     * @param fields the fields to retrieve.
066     * @return an iterable contains information about all file version retentions matching given filter.
067     */
068    public static Iterable<BoxFileVersionRetention.Info> getRetentions(
069        final BoxAPIConnection api, QueryFilter filter, String... fields) {
070        filter.addFields(fields);
071        return new BoxResourceIterable<BoxFileVersionRetention.Info>(api,
072            ALL_RETENTIONS_URL_TEMPLATE.buildWithQuery(api.getBaseURL(), filter.toString()),
073            DEFAULT_LIMIT) {
074
075            @Override
076            protected BoxFileVersionRetention.Info factory(JsonObject jsonObject) {
077                BoxFileVersionRetention retention = new BoxFileVersionRetention(api, jsonObject.get("id").asString());
078                return retention.new Info(jsonObject);
079            }
080        };
081    }
082
083    /**
084     * @param fields the fields to retrieve.
085     * @return information about this retention policy.
086     */
087    public BoxFileVersionRetention.Info getInfo(String... fields) {
088        QueryStringBuilder builder = new QueryStringBuilder();
089        if (fields.length > 0) {
090            builder.appendParam("fields", fields);
091        }
092        URL url = RETENTION_URL_TEMPLATE.buildWithQuery(this.getAPI().getBaseURL(), builder.toString(), this.getID());
093        BoxJSONRequest request = new BoxJSONRequest(this.getAPI(), url, "GET");
094        try (BoxJSONResponse response = request.send()) {
095            JsonObject responseJSON = Json.parse(response.getJSON()).asObject();
096            return new Info(responseJSON);
097        }
098    }
099
100    /**
101     * Represents possible query filters for "Get File Version Retentions" function.
102     */
103    public static class QueryFilter extends QueryStringBuilder {
104
105        /**
106         * Param name for the file id to filter the file version retentions by.
107         */
108        private static final String PARAM_FILE_ID = "file_id";
109
110        /**
111         * Param name for the file version id to filter the file version retentions by.
112         */
113        private static final String PARAM_FILE_VERSION_ID = "file_version_id";
114
115        /**
116         * Param name for the policy id to filter the file version retentions by.
117         */
118        private static final String PARAM_POLICY_ID = "policy_id";
119
120        /**
121         * Param name for the disposition action of the retention policy.
122         */
123        private static final String PARAM_DISPOSITION_ACTION = "disposition_action";
124
125        /**
126         * Param name for the datetime to filter file version retentions.
127         */
128        private static final String PARAM_DISPOSITION_BEFORE = "disposition_before";
129
130        /**
131         * Param name for the datetime to filter file version retentions.
132         */
133        private static final String PARAM_DISPOSITION_AFTER = "disposition_after";
134
135        /**
136         * Param name for the the fields to retrieve.
137         */
138        private static final String PARAM_FIELDS = "fields";
139
140        /**
141         * Constructs empty query filter.
142         */
143        public QueryFilter() {
144            super();
145        }
146
147        /**
148         * @param id a file id to filter the file version retentions by.
149         * @return modified query filter.
150         */
151        public QueryFilter addFileID(String id) {
152            this.appendParam(PARAM_FILE_ID, id);
153            return this;
154        }
155
156        /**
157         * @param id a file version id to filter the file version retentions by.
158         * @return modified query filter.
159         */
160        public QueryFilter addFileVersionID(String id) {
161            this.appendParam(PARAM_FILE_VERSION_ID, id);
162            return this;
163        }
164
165        /**
166         * @param id a policy id to filter the file version retentions by.
167         * @return modified query filter.
168         */
169        public QueryFilter addPolicyID(String id) {
170            this.appendParam(PARAM_POLICY_ID, id);
171            return this;
172        }
173
174        /**
175         * The action can be "permanently_delete" or "remove_retention".
176         *
177         * @param action the disposition action of the retention policy.
178         * @return modified query filter.
179         */
180        public QueryFilter addDispositionAction(String action) {
181            this.appendParam(PARAM_DISPOSITION_ACTION, action);
182            return this;
183        }
184
185        /**
186         * @param date the datetime to filter file version retentions.
187         * @return modified query filter.
188         */
189        public QueryFilter addDispositionBefore(Date date) {
190            this.appendParam(PARAM_DISPOSITION_BEFORE, BoxDateFormat.format(date));
191            return this;
192        }
193
194        /**
195         * @param date the datetime to filter file version retentions.
196         * @return modified query filter.
197         */
198        public QueryFilter addDispositionAfter(Date date) {
199            this.appendParam(PARAM_DISPOSITION_AFTER, BoxDateFormat.format(date));
200            return this;
201        }
202
203        /**
204         * @param fields the fields to retrieve.
205         * @return modified query filter.
206         */
207        public QueryFilter addFields(String... fields) {
208            if (fields.length > 0) {
209                this.appendParam(PARAM_FIELDS, fields);
210            }
211            return this;
212        }
213    }
214
215    /**
216     * Contains information about the retention policy.
217     */
218    public class Info extends BoxResource.Info {
219
220        /**
221         * @see #getFileVersion()
222         */
223        private BoxFileVersion fileVersion;
224
225        /**
226         * @see #getFile()
227         */
228        private BoxFile.Info file;
229
230        /**
231         * @see #getAppliedAt()
232         */
233        private Date appliedAt;
234
235        /**
236         * @see #getDispositionAt()
237         */
238        private Date dispositionAt;
239
240        /**
241         * @see #getWinningPolicy()
242         */
243        private BoxRetentionPolicy.Info winningPolicy;
244
245        /**
246         * Constructs an empty Info object.
247         */
248        public Info() {
249            super();
250        }
251
252        /**
253         * Constructs an Info object by parsing information from a JSON string.
254         *
255         * @param json the JSON string to parse.
256         */
257        public Info(String json) {
258            super(json);
259        }
260
261        /**
262         * Constructs an Info object using an already parsed JSON object.
263         *
264         * @param jsonObject the parsed JSON object.
265         */
266        Info(JsonObject jsonObject) {
267            super(jsonObject);
268        }
269
270        /**
271         * {@inheritDoc}
272         */
273        @Override
274        public BoxResource getResource() {
275            return BoxFileVersionRetention.this;
276        }
277
278        /**
279         * @return the file version this file version retention was applied to.
280         */
281        public BoxFileVersion getFileVersion() {
282            return this.fileVersion;
283        }
284
285        /**
286         * @return the file this file version retention was applied to.
287         */
288        public BoxFile.Info getFile() {
289            return this.file;
290        }
291
292        /**
293         * @return the time that this file version retention was created.
294         */
295        public Date getAppliedAt() {
296            return this.appliedAt;
297        }
298
299        /**
300         * @return the time that the retention period expires on this file version retention.
301         */
302        public Date getDispositionAt() {
303            return this.dispositionAt;
304        }
305
306        /**
307         * @return the winning retention policy applied to this file version retention.
308         */
309        public BoxRetentionPolicy.Info getWinningPolicy() {
310            return this.winningPolicy;
311        }
312
313        /**
314         * {@inheritDoc}
315         */
316        @Override
317        void parseJSONMember(JsonObject.Member member) {
318            super.parseJSONMember(member);
319            String memberName = member.getName();
320            JsonValue value = member.getValue();
321            try {
322                switch (memberName) {
323                    case "winning_retention_policy":
324                        JsonObject policyJSON = value.asObject();
325                        if (this.winningPolicy == null) {
326                            String policyID = policyJSON.get("id").asString();
327                            BoxRetentionPolicy policy = new BoxRetentionPolicy(getAPI(), policyID);
328                            this.winningPolicy = policy.new Info(policyJSON);
329                        } else {
330                            this.winningPolicy.update(policyJSON);
331                        }
332                        break;
333                    case "file":
334                        JsonObject fileJSON = value.asObject();
335                        if (this.file == null) {
336                            String fileID = fileJSON.get("id").asString();
337                            BoxFile file = new BoxFile(getAPI(), fileID);
338                            this.file = file.new Info(fileJSON);
339                        } else {
340                            this.file.update(fileJSON);
341                        }
342                        break;
343                    case "file_version":
344                        JsonObject versionJSON = value.asObject();
345                        String fileVersionID = versionJSON.get("id").asString();
346                        this.fileVersion = new BoxFileVersion(getAPI(), versionJSON, fileVersionID);
347                        break;
348                    case "applied_at":
349                        this.appliedAt = BoxDateFormat.parse(value.asString());
350                        break;
351                    case "disposition_at":
352                        this.dispositionAt = BoxDateFormat.parse(value.asString());
353                        break;
354                    default:
355                        break;
356                }
357            } catch (Exception e) {
358                throw new BoxDeserializationException(memberName, value.toString(), e);
359            }
360        }
361    }
362}