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}