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