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