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}