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        BoxJSONResponse response = (BoxJSONResponse) request.send();
101        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
102
103        BoxFolder restoredFolder = new BoxFolder(this.api, responseJSON.get("id").asString());
104        return restoredFolder.new Info(responseJSON);
105    }
106
107    /**
108     * Restores a trashed folder to a new location with a new name.
109     * @param  folderID    the ID of the trashed folder.
110     * @param  newName     an optional new name to give the folder. This can be null to use the folder's original name.
111     * @param  newParentID an optional new parent ID for the folder. This can be null to use the folder's original
112     *                     parent.
113     * @return             info about the restored folder.
114     */
115    public BoxFolder.Info restoreFolder(String folderID, String newName, String newParentID) {
116        JsonObject requestJSON = new JsonObject();
117
118        if (newName != null) {
119            requestJSON.add("name", newName);
120        }
121
122        if (newParentID != null) {
123            JsonObject parent = new JsonObject();
124            parent.add("id", newParentID);
125            requestJSON.add("parent", parent);
126        }
127
128        URL url = RESTORE_FOLDER_URL_TEMPLATE.build(this.api.getBaseURL(), folderID);
129        BoxJSONRequest request = new BoxJSONRequest(this.api, url, "POST");
130        request.setBody(requestJSON.toString());
131        BoxJSONResponse response = (BoxJSONResponse) request.send();
132        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
133
134        BoxFolder restoredFolder = new BoxFolder(this.api, responseJSON.get("id").asString());
135        return restoredFolder.new Info(responseJSON);
136    }
137
138    /**
139     * Permanently deletes a trashed file.
140     * @param fileID the ID of the trashed folder to permanently delete.
141     */
142    public void deleteFile(String fileID) {
143        URL url = FILE_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
144        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "DELETE");
145        BoxAPIResponse response = request.send();
146        response.disconnect();
147    }
148
149    /**
150     * Gets information about a trashed file.
151     * @param  fileID the ID of the trashed file.
152     * @return        info about the trashed file.
153     */
154    public BoxFile.Info getFileInfo(String fileID) {
155        URL url = FILE_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
156        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET");
157        BoxJSONResponse response = (BoxJSONResponse) request.send();
158        JsonObject jsonObject = JsonObject.readFrom(response.getJSON());
159
160        BoxFile file = new BoxFile(this.api, jsonObject.get("id").asString());
161        return file.new Info(response.getJSON());
162    }
163
164    /**
165     * Gets information about a trashed file that's limited to a list of specified fields.
166     * @param  fileID the ID of the trashed file.
167     * @param  fields the fields to retrieve.
168     * @return        info about the trashed file containing only the specified fields.
169     */
170    public BoxFile.Info getFileInfo(String fileID, String... fields) {
171        String queryString = new QueryStringBuilder().appendParam("fields", fields).toString();
172        URL url = FILE_INFO_URL_TEMPLATE.buildWithQuery(this.api.getBaseURL(), queryString, fileID);
173        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET");
174        BoxJSONResponse response = (BoxJSONResponse) request.send();
175        JsonObject jsonObject = JsonObject.readFrom(response.getJSON());
176
177        BoxFile file = new BoxFile(this.api, jsonObject.get("id").asString());
178        return file.new Info(response.getJSON());
179    }
180
181    /**
182     * Restores a trashed file back to its original location.
183     * @param  fileID the ID of the trashed file.
184     * @return        info about the restored file.
185     */
186    public BoxFile.Info restoreFile(String fileID) {
187        URL url = RESTORE_FILE_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
188        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "POST");
189        BoxJSONResponse response = (BoxJSONResponse) request.send();
190        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
191
192        BoxFile restoredFile = new BoxFile(this.api, responseJSON.get("id").asString());
193        return restoredFile.new Info(responseJSON);
194    }
195
196    /**
197     * Restores a trashed file to a new location with a new name.
198     * @param  fileID      the ID of the trashed file.
199     * @param  newName     an optional new name to give the file. This can be null to use the file's original name.
200     * @param  newParentID an optional new parent ID for the file. This can be null to use the file's original
201     *                     parent.
202     * @return             info about the restored file.
203     */
204    public BoxFile.Info restoreFile(String fileID, String newName, String newParentID) {
205        JsonObject requestJSON = new JsonObject();
206
207        if (newName != null) {
208            requestJSON.add("name", newName);
209        }
210
211        if (newParentID != null) {
212            JsonObject parent = new JsonObject();
213            parent.add("id", newParentID);
214            requestJSON.add("parent", parent);
215        }
216
217        URL url = RESTORE_FILE_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
218        BoxJSONRequest request = new BoxJSONRequest(this.api, url, "POST");
219        request.setBody(requestJSON.toString());
220        BoxJSONResponse response = (BoxJSONResponse) request.send();
221        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
222
223        BoxFile restoredFile = new BoxFile(this.api, responseJSON.get("id").asString());
224        return restoredFile.new Info(responseJSON);
225    }
226
227    /**
228     * Returns an iterator over the items in the trash.
229     * @return an iterator over the items in the trash.
230     */
231    public Iterator<BoxItem.Info> iterator() {
232        URL url = GET_ITEMS_URL.build(this.api.getBaseURL());
233        return new BoxItemIterator(this.api, url);
234    }
235}