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