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}