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 */
011public class BoxTrash implements Iterable<BoxItem.Info> {
012    private static final long LIMIT = 1000;
013    private static final URLTemplate GET_ITEMS_URL = new URLTemplate("folders/trash/items/");
014    private static final URLTemplate FOLDER_INFO_URL_TEMPLATE = new URLTemplate("folders/%s/trash");
015    private static final URLTemplate FILE_INFO_URL_TEMPLATE = new URLTemplate("files/%s/trash");
016    private static final URLTemplate RESTORE_FILE_URL_TEMPLATE = new URLTemplate("files/%s");
017    private static final URLTemplate RESTORE_FOLDER_URL_TEMPLATE = new URLTemplate("folders/%s");
018
019    private final BoxAPIConnection api;
020
021    /**
022     * Constructs a BoxTrash using a given API connection.
023     * @param  api the API connection to be used by the trash.
024     */
025    public BoxTrash(BoxAPIConnection api) {
026        this.api = api;
027    }
028
029    /**
030     * Permanently deletes a trashed folder.
031     * @param folderID the ID of the trashed folder to permanently delete.
032     */
033    public void deleteFolder(String folderID) {
034        URL url = FOLDER_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), folderID);
035        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "DELETE");
036        BoxAPIResponse response = request.send();
037        response.disconnect();
038    }
039
040    /**
041     * Gets information about a trashed folder.
042     * @param  folderID the ID of the trashed folder.
043     * @return          info about the trashed folder.
044     */
045    public BoxFolder.Info getFolderInfo(String folderID) {
046        URL url = FOLDER_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), folderID);
047        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET");
048        BoxJSONResponse response = (BoxJSONResponse) request.send();
049        JsonObject jsonObject = JsonObject.readFrom(response.getJSON());
050
051        BoxFolder folder = new BoxFolder(this.api, jsonObject.get("id").asString());
052        return folder.new Info(response.getJSON());
053    }
054
055    /**
056     * Gets information about a trashed folder that's limited to a list of specified fields.
057     * @param  folderID the ID of the trashed folder.
058     * @param  fields   the fields to retrieve.
059     * @return          info about the trashed folder containing only the specified fields.
060     */
061    public BoxFolder.Info getFolderInfo(String folderID, String... fields) {
062        String queryString = new QueryStringBuilder().appendParam("fields", fields).toString();
063        URL url = FOLDER_INFO_URL_TEMPLATE.buildWithQuery(this.api.getBaseURL(), queryString, folderID);
064        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET");
065        BoxJSONResponse response = (BoxJSONResponse) request.send();
066        JsonObject jsonObject = JsonObject.readFrom(response.getJSON());
067
068        BoxFolder folder = new BoxFolder(this.api, jsonObject.get("id").asString());
069        return folder.new Info(response.getJSON());
070    }
071
072    /**
073     * Restores a trashed folder back to its original location.
074     * @param  folderID the ID of the trashed folder.
075     * @return          info about the restored folder.
076     */
077    public BoxFolder.Info restoreFolder(String folderID) {
078        URL url = RESTORE_FOLDER_URL_TEMPLATE.build(this.api.getBaseURL(), folderID);
079        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "POST");
080        BoxJSONResponse response = (BoxJSONResponse) request.send();
081        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
082
083        BoxFolder restoredFolder = new BoxFolder(this.api, responseJSON.get("id").asString());
084        return restoredFolder.new Info(responseJSON);
085    }
086
087    /**
088     * Restores a trashed folder to a new location with a new name.
089     * @param  folderID    the ID of the trashed folder.
090     * @param  newName     an optional new name to give the folder. This can be null to use the folder's original name.
091     * @param  newParentID an optional new parent ID for the folder. This can be null to use the folder's original
092     *                     parent.
093     * @return             info about the restored folder.
094     */
095    public BoxFolder.Info restoreFolder(String folderID, String newName, String newParentID) {
096        JsonObject requestJSON = new JsonObject();
097
098        if (newName != null) {
099            requestJSON.add("name", newName);
100        }
101
102        if (newParentID != null) {
103            JsonObject parent = new JsonObject();
104            parent.add("id", newParentID);
105            requestJSON.add("parent", parent);
106        }
107
108        URL url = RESTORE_FOLDER_URL_TEMPLATE.build(this.api.getBaseURL(), folderID);
109        BoxJSONRequest request = new BoxJSONRequest(this.api, url, "POST");
110        request.setBody(requestJSON.toString());
111        BoxJSONResponse response = (BoxJSONResponse) request.send();
112        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
113
114        BoxFolder restoredFolder = new BoxFolder(this.api, responseJSON.get("id").asString());
115        return restoredFolder.new Info(responseJSON);
116    }
117
118    /**
119     * Permanently deletes a trashed file.
120     * @param fileID the ID of the trashed folder to permanently delete.
121     */
122    public void deleteFile(String fileID) {
123        URL url = FILE_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
124        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "DELETE");
125        BoxAPIResponse response = request.send();
126        response.disconnect();
127    }
128
129    /**
130     * Gets information about a trashed file.
131     * @param  fileID the ID of the trashed file.
132     * @return        info about the trashed file.
133     */
134    public BoxFile.Info getFileInfo(String fileID) {
135        URL url = FILE_INFO_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
136        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET");
137        BoxJSONResponse response = (BoxJSONResponse) request.send();
138        JsonObject jsonObject = JsonObject.readFrom(response.getJSON());
139
140        BoxFile file = new BoxFile(this.api, jsonObject.get("id").asString());
141        return file.new Info(response.getJSON());
142    }
143
144    /**
145     * Gets information about a trashed file that's limited to a list of specified fields.
146     * @param  fileID the ID of the trashed file.
147     * @param  fields the fields to retrieve.
148     * @return        info about the trashed file containing only the specified fields.
149     */
150    public BoxFile.Info getFileInfo(String fileID, String... fields) {
151        String queryString = new QueryStringBuilder().appendParam("fields", fields).toString();
152        URL url = FILE_INFO_URL_TEMPLATE.buildWithQuery(this.api.getBaseURL(), queryString, fileID);
153        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "GET");
154        BoxJSONResponse response = (BoxJSONResponse) request.send();
155        JsonObject jsonObject = JsonObject.readFrom(response.getJSON());
156
157        BoxFile file = new BoxFile(this.api, jsonObject.get("id").asString());
158        return file.new Info(response.getJSON());
159    }
160
161    /**
162     * Restores a trashed file back to its original location.
163     * @param  fileID the ID of the trashed file.
164     * @return        info about the restored file.
165     */
166    public BoxFile.Info restoreFile(String fileID) {
167        URL url = RESTORE_FILE_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
168        BoxAPIRequest request = new BoxAPIRequest(this.api, url, "POST");
169        BoxJSONResponse response = (BoxJSONResponse) request.send();
170        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
171
172        BoxFile restoredFile = new BoxFile(this.api, responseJSON.get("id").asString());
173        return restoredFile.new Info(responseJSON);
174    }
175
176    /**
177     * Restores a trashed file to a new location with a new name.
178     * @param  fileID      the ID of the trashed file.
179     * @param  newName     an optional new name to give the file. This can be null to use the file's original name.
180     * @param  newParentID an optional new parent ID for the file. This can be null to use the file's original
181     *                     parent.
182     * @return             info about the restored file.
183     */
184    public BoxFile.Info restoreFile(String fileID, String newName, String newParentID) {
185        JsonObject requestJSON = new JsonObject();
186
187        if (newName != null) {
188            requestJSON.add("name", newName);
189        }
190
191        if (newParentID != null) {
192            JsonObject parent = new JsonObject();
193            parent.add("id", newParentID);
194            requestJSON.add("parent", parent);
195        }
196
197        URL url = RESTORE_FILE_URL_TEMPLATE.build(this.api.getBaseURL(), fileID);
198        BoxJSONRequest request = new BoxJSONRequest(this.api, url, "POST");
199        request.setBody(requestJSON.toString());
200        BoxJSONResponse response = (BoxJSONResponse) request.send();
201        JsonObject responseJSON = JsonObject.readFrom(response.getJSON());
202
203        BoxFile restoredFile = new BoxFile(this.api, responseJSON.get("id").asString());
204        return restoredFile.new Info(responseJSON);
205    }
206
207    /**
208     * Returns an iterator over the items in the trash.
209     * @return an iterator over the items in the trash.
210     */
211    public Iterator<BoxItem.Info> iterator() {
212        URL url = GET_ITEMS_URL.build(this.api.getBaseURL());
213        return new BoxItemIterator(this.api, url);
214    }
215}