001package com.box.sdk; 002 003import com.eclipsesource.json.JsonObject; 004import java.net.URL; 005import java.util.Iterator; 006 007/** 008 * Provides methods for deleting, recovering, and viewing a user's trashed files and folders. 009 * 010 * <p>Unless otherwise noted, the methods in this class can throw an unchecked {@link BoxAPIException} (unchecked 011 * meaning that the compiler won't force you to handle it) if an error occurs. If you wish to implement custom error 012 * handling for errors related to the Box REST API, you should capture this exception explicitly.</p> 013 */ 014public class BoxTrash implements Iterable<BoxItem.Info> { 015 016 /** 017 * Get Item URL Template. 018 */ 019 public static final URLTemplate GET_ITEMS_URL = new URLTemplate("folders/trash/items/"); 020 /** 021 * Folder Info URL Template. 022 */ 023 public static final URLTemplate FOLDER_INFO_URL_TEMPLATE = new URLTemplate("folders/%s/trash"); 024 /** 025 * File Info URL Template. 026 */ 027 public static final URLTemplate FILE_INFO_URL_TEMPLATE = new URLTemplate("files/%s/trash"); 028 /** 029 * Restore File URL Template. 030 */ 031 public static final URLTemplate RESTORE_FILE_URL_TEMPLATE = new URLTemplate("files/%s"); 032 /** 033 * Restore Folder URL Template. 034 */ 035 public static final URLTemplate RESTORE_FOLDER_URL_TEMPLATE = new URLTemplate("folders/%s"); 036 037 private static final long LIMIT = 1000; 038 private final BoxAPIConnection api; 039 040 /** 041 * Constructs a BoxTrash using a given API connection. 042 * 043 * @param api the API connection to be used by the trash. 044 */ 045 public BoxTrash(BoxAPIConnection api) { 046 this.api = api; 047 } 048 049 /** 050 * Permanently deletes a trashed folder. 051 * 052 * @param folderID the ID of the trashed folder to permanently delete. 053 */ 054 public void deleteFolder(String folderID) { 055 URL url = FOLDER_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), folderID); 056 BoxAPIRequest request = new BoxAPIRequest(this.api, url, "DELETE"); 057 BoxAPIResponse response = request.send(); 058 response.disconnect(); 059 } 060 061 /** 062 * Gets information about a trashed folder. 063 * 064 * @param folderID the ID of the trashed folder. 065 * @return info about the trashed folder. 066 */ 067 public BoxFolder.Info getFolderInfo(String folderID) { 068 URL url = FOLDER_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), folderID); 069 BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET"); 070 BoxJSONResponse response = (BoxJSONResponse) request.send(); 071 JsonObject jsonObject = JsonObject.readFrom(response.getJSON()); 072 073 BoxFolder folder = new BoxFolder(this.api, jsonObject.get("id").asString()); 074 return folder.new Info(response.getJSON()); 075 } 076 077 /** 078 * Gets information about a trashed folder that's limited to a list of specified fields. 079 * 080 * @param folderID the ID of the trashed folder. 081 * @param fields the fields to retrieve. 082 * @return info about the trashed folder containing only the specified fields. 083 */ 084 public BoxFolder.Info getFolderInfo(String folderID, String... fields) { 085 String queryString = new QueryStringBuilder().appendParam("fields", fields).toString(); 086 URL url = FOLDER_INFO_URL_TEMPLATE.buildWithQuery(this.api.getBaseURL(), queryString, folderID); 087 BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET"); 088 BoxJSONResponse response = (BoxJSONResponse) request.send(); 089 JsonObject jsonObject = JsonObject.readFrom(response.getJSON()); 090 091 BoxFolder folder = new BoxFolder(this.api, jsonObject.get("id").asString()); 092 return folder.new Info(response.getJSON()); 093 } 094 095 /** 096 * Restores a trashed folder back to its original location. 097 * 098 * @param folderID the ID of the trashed folder. 099 * @return info about the restored folder. 100 */ 101 public BoxFolder.Info restoreFolder(String folderID) { 102 URL url = RESTORE_FOLDER_URL_TEMPLATE.build(this.api.getBaseURL(), folderID); 103 BoxAPIRequest request = new BoxAPIRequest(this.api, url, "POST"); 104 JsonObject requestJSON = new JsonObject() 105 .add("", ""); 106 request.setBody(requestJSON.toString()); 107 BoxJSONResponse response = (BoxJSONResponse) request.send(); 108 JsonObject responseJSON = JsonObject.readFrom(response.getJSON()); 109 110 BoxFolder restoredFolder = new BoxFolder(this.api, responseJSON.get("id").asString()); 111 return restoredFolder.new Info(responseJSON); 112 } 113 114 /** 115 * Restores a trashed folder to a new location with a new name. 116 * 117 * @param folderID the ID of the trashed folder. 118 * @param newName an optional new name to give the folder. This can be null to use the folder's original name. 119 * @param newParentID an optional new parent ID for the folder. This can be null to use the folder's original 120 * parent. 121 * @return info about the restored folder. 122 */ 123 public BoxFolder.Info restoreFolder(String folderID, String newName, String newParentID) { 124 JsonObject requestJSON = new JsonObject(); 125 126 if (newName != null) { 127 requestJSON.add("name", newName); 128 } 129 130 if (newParentID != null) { 131 JsonObject parent = new JsonObject(); 132 parent.add("id", newParentID); 133 requestJSON.add("parent", parent); 134 } 135 136 URL url = RESTORE_FOLDER_URL_TEMPLATE.build(this.api.getBaseURL(), folderID); 137 BoxJSONRequest request = new BoxJSONRequest(this.api, url, "POST"); 138 request.setBody(requestJSON.toString()); 139 BoxJSONResponse response = (BoxJSONResponse) request.send(); 140 JsonObject responseJSON = JsonObject.readFrom(response.getJSON()); 141 142 BoxFolder restoredFolder = new BoxFolder(this.api, responseJSON.get("id").asString()); 143 return restoredFolder.new Info(responseJSON); 144 } 145 146 /** 147 * Permanently deletes a trashed file. 148 * 149 * @param fileID the ID of the trashed folder to permanently delete. 150 */ 151 public void deleteFile(String fileID) { 152 URL url = FILE_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), fileID); 153 BoxAPIRequest request = new BoxAPIRequest(this.api, url, "DELETE"); 154 BoxAPIResponse response = request.send(); 155 response.disconnect(); 156 } 157 158 /** 159 * Gets information about a trashed file. 160 * 161 * @param fileID the ID of the trashed file. 162 * @return info about the trashed file. 163 */ 164 public BoxFile.Info getFileInfo(String fileID) { 165 URL url = FILE_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), fileID); 166 BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET"); 167 BoxJSONResponse response = (BoxJSONResponse) request.send(); 168 JsonObject jsonObject = JsonObject.readFrom(response.getJSON()); 169 170 BoxFile file = new BoxFile(this.api, jsonObject.get("id").asString()); 171 return file.new Info(response.getJSON()); 172 } 173 174 /** 175 * Gets information about a trashed file that's limited to a list of specified fields. 176 * 177 * @param fileID the ID of the trashed file. 178 * @param fields the fields to retrieve. 179 * @return info about the trashed file containing only the specified fields. 180 */ 181 public BoxFile.Info getFileInfo(String fileID, String... fields) { 182 String queryString = new QueryStringBuilder().appendParam("fields", fields).toString(); 183 URL url = FILE_INFO_URL_TEMPLATE.buildWithQuery(this.api.getBaseURL(), queryString, fileID); 184 BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET"); 185 BoxJSONResponse response = (BoxJSONResponse) request.send(); 186 JsonObject jsonObject = JsonObject.readFrom(response.getJSON()); 187 188 BoxFile file = new BoxFile(this.api, jsonObject.get("id").asString()); 189 return file.new Info(response.getJSON()); 190 } 191 192 /** 193 * Restores a trashed file back to its original location. 194 * 195 * @param fileID the ID of the trashed file. 196 * @return info about the restored file. 197 */ 198 public BoxFile.Info restoreFile(String fileID) { 199 URL url = RESTORE_FILE_URL_TEMPLATE.build(this.api.getBaseURL(), fileID); 200 BoxAPIRequest request = new BoxAPIRequest(this.api, url, "POST"); 201 JsonObject requestJSON = new JsonObject() 202 .add("", ""); 203 request.setBody(requestJSON.toString()); 204 BoxJSONResponse response = (BoxJSONResponse) request.send(); 205 JsonObject responseJSON = JsonObject.readFrom(response.getJSON()); 206 207 BoxFile restoredFile = new BoxFile(this.api, responseJSON.get("id").asString()); 208 return restoredFile.new Info(responseJSON); 209 } 210 211 /** 212 * Restores a trashed file to a new location with a new name. 213 * 214 * @param fileID the ID of the trashed file. 215 * @param newName an optional new name to give the file. This can be null to use the file's original name. 216 * @param newParentID an optional new parent ID for the file. This can be null to use the file's original 217 * parent. 218 * @return info about the restored file. 219 */ 220 public BoxFile.Info restoreFile(String fileID, String newName, String newParentID) { 221 JsonObject requestJSON = new JsonObject(); 222 223 if (newName != null) { 224 requestJSON.add("name", newName); 225 } 226 227 if (newParentID != null) { 228 JsonObject parent = new JsonObject(); 229 parent.add("id", newParentID); 230 requestJSON.add("parent", parent); 231 } 232 233 URL url = RESTORE_FILE_URL_TEMPLATE.build(this.api.getBaseURL(), fileID); 234 BoxJSONRequest request = new BoxJSONRequest(this.api, url, "POST"); 235 request.setBody(requestJSON.toString()); 236 BoxJSONResponse response = (BoxJSONResponse) request.send(); 237 JsonObject responseJSON = JsonObject.readFrom(response.getJSON()); 238 239 BoxFile restoredFile = new BoxFile(this.api, responseJSON.get("id").asString()); 240 return restoredFile.new Info(responseJSON); 241 } 242 243 /** 244 * Returns an iterator over the items in the trash. 245 * 246 * @return an iterator over the items in the trash. 247 */ 248 public Iterator<BoxItem.Info> iterator() { 249 URL url = GET_ITEMS_URL.build(this.api.getBaseURL()); 250 return new BoxItemIterator(this.api, url); 251 } 252}