001package com.box.sdk;
002
003import com.eclipsesource.json.Json;
004import com.eclipsesource.json.JsonObject;
005import java.net.URL;
006import java.util.Iterator;
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     *
044     * @param api the API connection to be used by the trash.
045     */
046    public BoxTrash(BoxAPIConnection api) {
047        this.api = api;
048    }
049
050    /**
051     * Permanently deletes a trashed folder.
052     *
053     * @param folderID the ID of the trashed folder to permanently delete.
054     */
055    public void deleteFolder(String folderID) {
056        URL url = FOLDER_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), folderID);
057        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "DELETE");
058        BoxAPIResponse response = request.send();
059        response.disconnect();
060    }
061
062    /**
063     * Gets information about a trashed folder.
064     *
065     * @param folderID the ID of the trashed folder.
066     * @return info about the trashed folder.
067     */
068    public BoxFolder.Info getFolderInfo(String folderID) {
069        URL url = FOLDER_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), folderID);
070        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET");
071        BoxJSONResponse response = (BoxJSONResponse) request.send();
072        JsonObject jsonObject = Json.parse(response.getJSON()).asObject();
073
074        BoxFolder folder = new BoxFolder(this.api, jsonObject.get("id").asString());
075        return folder.new Info(response.getJSON());
076    }
077
078    /**
079     * Gets information about a trashed folder that's limited to a list of specified fields.
080     *
081     * @param folderID the ID of the trashed folder.
082     * @param fields   the fields to retrieve.
083     * @return info about the trashed folder containing only the specified fields.
084     */
085    public BoxFolder.Info getFolderInfo(String folderID, String... fields) {
086        String queryString = new QueryStringBuilder().appendParam("fields", fields).toString();
087        URL url = FOLDER_INFO_URL_TEMPLATE.buildWithQuery(this.api.getBaseURL(), queryString, folderID);
088        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET");
089        BoxJSONResponse response = (BoxJSONResponse) request.send();
090        JsonObject jsonObject = Json.parse(response.getJSON()).asObject();
091
092        BoxFolder folder = new BoxFolder(this.api, jsonObject.get("id").asString());
093        return folder.new Info(response.getJSON());
094    }
095
096    /**
097     * Restores a trashed folder back to its original location.
098     *
099     * @param folderID the ID of the trashed folder.
100     * @return info about the restored folder.
101     */
102    public BoxFolder.Info restoreFolder(String folderID) {
103        URL url = RESTORE_FOLDER_URL_TEMPLATE.build(this.api.getBaseURL(), folderID);
104        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "POST");
105        JsonObject requestJSON = new JsonObject()
106            .add("", "");
107        request.setBody(requestJSON.toString());
108        BoxJSONResponse response = (BoxJSONResponse) request.send();
109        JsonObject responseJSON = Json.parse(response.getJSON()).asObject();
110
111        BoxFolder restoredFolder = new BoxFolder(this.api, responseJSON.get("id").asString());
112        return restoredFolder.new Info(responseJSON);
113    }
114
115    /**
116     * Restores a trashed folder to a new location with a new name.
117     *
118     * @param folderID    the ID of the trashed folder.
119     * @param newName     an optional new name to give the folder. This can be null to use the folder's original name.
120     * @param newParentID an optional new parent ID for the folder. This can be null to use the folder's original
121     *                    parent.
122     * @return info about the restored folder.
123     */
124    public BoxFolder.Info restoreFolder(String folderID, String newName, String newParentID) {
125        JsonObject requestJSON = new JsonObject();
126
127        if (newName != null) {
128            requestJSON.add("name", newName);
129        }
130
131        if (newParentID != null) {
132            JsonObject parent = new JsonObject();
133            parent.add("id", newParentID);
134            requestJSON.add("parent", parent);
135        }
136
137        URL url = RESTORE_FOLDER_URL_TEMPLATE.build(this.api.getBaseURL(), folderID);
138        BoxJSONRequest request = new BoxJSONRequest(this.api, url, "POST");
139        request.setBody(requestJSON.toString());
140        BoxJSONResponse response = (BoxJSONResponse) request.send();
141        JsonObject responseJSON = Json.parse(response.getJSON()).asObject();
142
143        BoxFolder restoredFolder = new BoxFolder(this.api, responseJSON.get("id").asString());
144        return restoredFolder.new Info(responseJSON);
145    }
146
147    /**
148     * Permanently deletes a trashed file.
149     *
150     * @param fileID the ID of the trashed folder to permanently delete.
151     */
152    public void deleteFile(String fileID) {
153        URL url = FILE_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
154        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "DELETE");
155        BoxAPIResponse response = request.send();
156        response.disconnect();
157    }
158
159    /**
160     * Gets information about a trashed file.
161     *
162     * @param fileID the ID of the trashed file.
163     * @return info about the trashed file.
164     */
165    public BoxFile.Info getFileInfo(String fileID) {
166        URL url = FILE_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
167        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET");
168        BoxJSONResponse response = (BoxJSONResponse) request.send();
169        JsonObject jsonObject = Json.parse(response.getJSON()).asObject();
170
171        BoxFile file = new BoxFile(this.api, jsonObject.get("id").asString());
172        return file.new Info(response.getJSON());
173    }
174
175    /**
176     * Gets information about a trashed file that's limited to a list of specified fields.
177     *
178     * @param fileID the ID of the trashed file.
179     * @param fields the fields to retrieve.
180     * @return info about the trashed file containing only the specified fields.
181     */
182    public BoxFile.Info getFileInfo(String fileID, String... fields) {
183        String queryString = new QueryStringBuilder().appendParam("fields", fields).toString();
184        URL url = FILE_INFO_URL_TEMPLATE.buildWithQuery(this.api.getBaseURL(), queryString, fileID);
185        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET");
186        BoxJSONResponse response = (BoxJSONResponse) request.send();
187        JsonObject jsonObject = Json.parse(response.getJSON()).asObject();
188
189        BoxFile file = new BoxFile(this.api, jsonObject.get("id").asString());
190        return file.new Info(response.getJSON());
191    }
192
193    /**
194     * Restores a trashed file back to its original location.
195     *
196     * @param fileID the ID of the trashed file.
197     * @return info about the restored file.
198     */
199    public BoxFile.Info restoreFile(String fileID) {
200        URL url = RESTORE_FILE_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
201        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "POST");
202        JsonObject requestJSON = new JsonObject()
203            .add("", "");
204        request.setBody(requestJSON.toString());
205        BoxJSONResponse response = (BoxJSONResponse) request.send();
206        JsonObject responseJSON = Json.parse(response.getJSON()).asObject();
207
208        BoxFile restoredFile = new BoxFile(this.api, responseJSON.get("id").asString());
209        return restoredFile.new Info(responseJSON);
210    }
211
212    /**
213     * Restores a trashed file to a new location with a new name.
214     *
215     * @param fileID      the ID of the trashed file.
216     * @param newName     an optional new name to give the file. This can be null to use the file's original name.
217     * @param newParentID an optional new parent ID for the file. This can be null to use the file's original
218     *                    parent.
219     * @return info about the restored file.
220     */
221    public BoxFile.Info restoreFile(String fileID, String newName, String newParentID) {
222        JsonObject requestJSON = new JsonObject();
223
224        if (newName != null) {
225            requestJSON.add("name", newName);
226        }
227
228        if (newParentID != null) {
229            JsonObject parent = new JsonObject();
230            parent.add("id", newParentID);
231            requestJSON.add("parent", parent);
232        }
233
234        URL url = RESTORE_FILE_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
235        BoxJSONRequest request = new BoxJSONRequest(this.api, url, "POST");
236        request.setBody(requestJSON.toString());
237        BoxJSONResponse response = (BoxJSONResponse) request.send();
238        JsonObject responseJSON = Json.parse(response.getJSON()).asObject();
239
240        BoxFile restoredFile = new BoxFile(this.api, responseJSON.get("id").asString());
241        return restoredFile.new Info(responseJSON);
242    }
243
244    /**
245     * Returns an iterator over the items in the trash.
246     *
247     * @return an iterator over the items in the trash.
248     */
249    public Iterator<BoxItem.Info> iterator() {
250        URL url = GET_ITEMS_URL.build(this.api.getBaseURL());
251        return new BoxItemIterator(this.api, url);
252    }
253}