diff --git a/doc/collaborations.md b/doc/collaborations.md index 5fcad1fa8..036b1c3e8 100644 --- a/doc/collaborations.md +++ b/doc/collaborations.md @@ -9,6 +9,7 @@ define what permissions a user has for a folder. * [Remove a Collaboration](#remove-a-collaboration) * [Get a Collaboration's Information](#get-a-collaborations-information) * [Get the Collaborations on a Folder](#get-the-collaborations-on-a-folder) +* [Get the Collaborations on a File](#get-the-collaborations-on-a-file) * [Get Pending Collaborations](#get-pending-collaborations) * [Accept or Decline a Pending Collaboration](#accept-or-decline-a-pending-collaboration) @@ -87,12 +88,26 @@ You can get all of the collaborations on a folder by calling [`getCollaborations()`][get-collaborations] on the folder. ```java -BoxFolder folder = new BoxFile(api, "id"); +BoxFolder folder = new BoxFolder(api, "id"); Collection collaborations = folder.getCollaborations(); ``` [get-collaborations]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getCollaborations-- +Get the Collaborations on a File +-------------------------------- + +You can get an iterator over all of the collaborations on a file by calling +[`BoxFile#getAllFileCollaborations(String... fields)`][get-collaborations-file] +on the file. + +```java +BoxFile file = new BoxFile(api, "id"); +Iterable collaborations = file.getAllFileCollaborations(); +``` + +[get-collaborations-file]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getAllFileCollaborations-java.lang.String...- + Get Pending Collaborations -------------------------- diff --git a/doc/files.md b/doc/files.md index 6795a8db6..4b2cfcb65 100644 --- a/doc/files.md +++ b/doc/files.md @@ -31,6 +31,7 @@ file's contents, upload new versions, and perform other common file operations * [Update Metadata](#update-metadata) * [Delete Metadata](#delete-metadata) * [Get All Metadata on File](#get-all-metadata-on-file) +* [Get File Representations](#get-file-representations) Get a File's Information ------------------------ @@ -639,3 +640,30 @@ for (Metadata metadata : metadataList) { ``` [get-all-metadata]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getAllMetadata-java.lang.String...- + +Get File Representations +------------------------ + +To get the preview representations of a file, call the +[`BoxFile#getInfoWithRepresentations(String representationHints, String... fields)`][get-reps] +method with the [representation hints][rep-hints] to fetch, along with any other +fields on the file object to fetch simultaneously. This method returns a [`BoxFile.Info`][box-file-info] +object that contains the representations as a list of [`Representation`][rep-obj] objects. + +Note that this method only provides information about a set of available representations; your +application will need to handle checking the status of the representations and downlaoding them +via the provided content URL template. + +```java +BoxFile file = new BoxFile(api, "1234"); + +// Get the PDF representation and file name +String repHints = "[pdf]"; +BoxFile.Info fileInfo = file.getInfoWithRepresentations(repHints, "name"); +List representations = fileInfo.getRepresentations(); +String name = fileInfo.getName(); +``` + +[get-reps]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getInfoWithRepresentations-java.lang.String-java.lang.String...- +[rep-hints]: https://developer.box.com/v2.0/reference/#section-x-rep-hints-header +[rep-obj]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/Representation.html diff --git a/doc/shared-items.md b/doc/shared-items.md new file mode 100644 index 000000000..e2ed6f467 --- /dev/null +++ b/doc/shared-items.md @@ -0,0 +1,43 @@ +Shared Items +============ + +Shared Items represent files and folders on Box accessed via a shared link. + +* [Get a Shared Item](#get-a-shared-item) + +Get a Shared Item +----------------- + +To get the file or folder information for a shared link, you can call +[`BoxItem.getSharedItem(BoxAPIConnection api, String sharedLink)`][get-shared-item] +with the shared link to get information about the item behind it. + +```java +String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456"; +BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink); +``` + +If the shared link is password-protected, call +[`BoxItem.getSharedItem(BoxAPIConnection api, String sharedLink, String password)`][get-shared-item-password] +with the shared link and password. + +```java +String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456"; +String password = "foo"; +BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink, password); +``` + +If you already know the type and ID of the item you want to access, you can +manually construct a [`SharedLinkAPIConnection`][shared-link-api] and make +API calls on the item directly. + +```java +String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456"; +SharedLinkAPIConnection sharedLinkAPI = new SharedLinkAPIConnection(api, sharedLink); + +BoxFile sharedFile = new BoxFile(sharedLinkAPI, "file_id"); +BoxFile.Info sharedFileInfo = sharedFile.getInfo(); +``` + +[get-shared-item]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.html#getSharedItem-com.box.sdk.BoxAPIConnection-java.lang.String- +[get-shared-item-password]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.html#getSharedItem-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String- diff --git a/src/main/java/com/box/sdk/BoxFile.java b/src/main/java/com/box/sdk/BoxFile.java index 3c5bde1bc..18005753b 100644 --- a/src/main/java/com/box/sdk/BoxFile.java +++ b/src/main/java/com/box/sdk/BoxFile.java @@ -518,7 +518,9 @@ public Collection getVersions() { * @param name the name to give the uploaded file or null to use existing name. * @param fileSize the size of the file used for account capacity calculations. * @param parentID the ID of the parent folder that the new version is being uploaded to. + * @deprecated This method will be removed in future versions of the SDK; use canUploadVersion(String, long) instead */ + @Deprecated public void canUploadVersion(String name, long fileSize, String parentID) { URL url = CONTENT_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID()); BoxJSONRequest request = new BoxJSONRequest(this.getAPI(), url, "OPTIONS"); @@ -539,6 +541,50 @@ public void canUploadVersion(String name, long fileSize, String parentID) { response.disconnect(); } + /** + * Checks if a new version of the file can be uploaded with the specified name. + * @param name the new name for the file. + * @return whether or not the file version can be uploaded. + */ + public boolean canUploadVersion(String name) { + return this.canUploadVersion(name, 0); + } + + /** + * Checks if a new version of the file can be uploaded with the specified name and size. + * @param name the new name for the file. + * @param fileSize the size of the new version content in bytes. + * @return whether or not the file version can be uploaded. + */ + public boolean canUploadVersion(String name, long fileSize) { + + URL url = CONTENT_URL_TEMPLATE.build(this.getAPI().getBaseURL(), this.getID()); + BoxJSONRequest request = new BoxJSONRequest(this.getAPI(), url, "OPTIONS"); + + JsonObject preflightInfo = new JsonObject(); + if (name != null) { + preflightInfo.add("name", name); + } + + preflightInfo.add("size", fileSize); + + request.setBody(preflightInfo.toString()); + try { + BoxAPIResponse response = request.send(); + + return response.getResponseCode() == 200; + } catch (BoxAPIException ex) { + + if (ex.getResponseCode() >= 400 && ex.getResponseCode() < 500) { + // This looks like an error response, menaing the upload would fail + return false; + } else { + // This looks like a network error or server error, rethrow exception + throw ex; + } + } + } + /** * Uploads a new version of this file, replacing the current version. Note that only users with premium accounts * will be able to view and recover previous versions of the file. @@ -1136,6 +1182,72 @@ public BoxFile.Info uploadLargeFile(InputStream inputStream, long fileSize, .upload(this.getAPI(), inputStream, url, fileSize); } + private BoxCollaboration.Info collaborate(JsonObject accessibleByField, BoxCollaboration.Role role, + Boolean notify, Boolean canViewPath) { + + JsonObject itemField = new JsonObject(); + itemField.add("id", this.getID()); + itemField.add("type", "file"); + + return BoxCollaboration.create(this.getAPI(), accessibleByField, itemField, role, notify, canViewPath); + } + + /** + * Adds a collaborator to this file. + * + * @param collaborator the collaborator to add. + * @param role the role of the collaborator. + * @param notify determines if the user (or all the users in the group) will receive email notifications. + * @param canViewPath whether view path collaboration feature is enabled or not. + * @return info about the new collaboration. + */ + public BoxCollaboration.Info collaborate(BoxCollaborator collaborator, BoxCollaboration.Role role, + Boolean notify, Boolean canViewPath) { + JsonObject accessibleByField = new JsonObject(); + accessibleByField.add("id", collaborator.getID()); + + if (collaborator instanceof BoxUser) { + accessibleByField.add("type", "user"); + } else if (collaborator instanceof BoxGroup) { + accessibleByField.add("type", "group"); + } else { + throw new IllegalArgumentException("The given collaborator is of an unknown type."); + } + return this.collaborate(accessibleByField, role, notify, canViewPath); + } + + + /** + * Adds a collaborator to this folder. An email will be sent to the collaborator if they don't already have a Box + * account. + * + * @param email the email address of the collaborator to add. + * @param role the role of the collaborator. + * @param notify determines if the user (or all the users in the group) will receive email notifications. + * @param canViewPath whether view path collaboration feature is enabled or not. + * @return info about the new collaboration. + */ + public BoxCollaboration.Info collaborate(String email, BoxCollaboration.Role role, + Boolean notify, Boolean canViewPath) { + JsonObject accessibleByField = new JsonObject(); + accessibleByField.add("login", email); + accessibleByField.add("type", "user"); + + return this.collaborate(accessibleByField, role, notify, canViewPath); + } + + /** + * Used to retrieve all collaborations associated with the item. + * + * @param fields the optional fields to retrieve. + * @return An iterable of metadata instances associated with the item. + */ + public BoxResourceIterable getAllFileCollaborations(String... fields) { + return BoxCollaboration.getAllFileCollaborations(this.getAPI(), this.getID(), + GET_COLLABORATORS_PAGE_SIZE, fields); + + } + /** * Contains information about a BoxFile. */ @@ -1438,69 +1550,4 @@ String toJSONValue() { } } - private BoxCollaboration.Info collaborate(JsonObject accessibleByField, BoxCollaboration.Role role, - Boolean notify, Boolean canViewPath) { - - JsonObject itemField = new JsonObject(); - itemField.add("id", this.getID()); - itemField.add("type", "file"); - - return BoxCollaboration.create(this.getAPI(), accessibleByField, itemField, role, notify, canViewPath); - } - - /** - * Adds a collaborator to this file. - * - * @param collaborator the collaborator to add. - * @param role the role of the collaborator. - * @param notify determines if the user (or all the users in the group) will receive email notifications. - * @param canViewPath whether view path collaboration feature is enabled or not. - * @return info about the new collaboration. - */ - public BoxCollaboration.Info collaborate(BoxCollaborator collaborator, BoxCollaboration.Role role, - Boolean notify, Boolean canViewPath) { - JsonObject accessibleByField = new JsonObject(); - accessibleByField.add("id", collaborator.getID()); - - if (collaborator instanceof BoxUser) { - accessibleByField.add("type", "user"); - } else if (collaborator instanceof BoxGroup) { - accessibleByField.add("type", "group"); - } else { - throw new IllegalArgumentException("The given collaborator is of an unknown type."); - } - return this.collaborate(accessibleByField, role, notify, canViewPath); - } - - - /** - * Adds a collaborator to this folder. An email will be sent to the collaborator if they don't already have a Box - * account. - * - * @param email the email address of the collaborator to add. - * @param role the role of the collaborator. - * @param notify determines if the user (or all the users in the group) will receive email notifications. - * @param canViewPath whether view path collaboration feature is enabled or not. - * @return info about the new collaboration. - */ - public BoxCollaboration.Info collaborate(String email, BoxCollaboration.Role role, - Boolean notify, Boolean canViewPath) { - JsonObject accessibleByField = new JsonObject(); - accessibleByField.add("login", email); - accessibleByField.add("type", "user"); - - return this.collaborate(accessibleByField, role, notify, canViewPath); - } - - /** - * Used to retrieve all collaborations associated with the item. - * - * @param fields the optional fields to retrieve. - * @return An iterable of metadata instances associated with the item. - */ - public BoxResourceIterable getAllFileCollaborations(String... fields) { - return BoxCollaboration.getAllFileCollaborations(this.getAPI(), this.getID(), - GET_COLLABORATORS_PAGE_SIZE, fields); - - } } diff --git a/src/main/java/com/box/sdk/SharedLinkAPIConnection.java b/src/main/java/com/box/sdk/SharedLinkAPIConnection.java index d05b39938..b633a2b01 100644 --- a/src/main/java/com/box/sdk/SharedLinkAPIConnection.java +++ b/src/main/java/com/box/sdk/SharedLinkAPIConnection.java @@ -4,7 +4,7 @@ * This API connection uses a shared link (along with an optional password) to authenticate with the Box API. It wraps a * preexisting BoxAPIConnection in order to provide additional access to items that are accessible with a shared link. */ -class SharedLinkAPIConnection extends BoxAPIConnection { +public class SharedLinkAPIConnection extends BoxAPIConnection { private final BoxAPIConnection wrappedConnection; private final String sharedLink; private final String sharedLinkPassword; diff --git a/src/test/java/com/box/sdk/BoxFileTest.java b/src/test/java/com/box/sdk/BoxFileTest.java index 2bb62c92f..0a424af53 100644 --- a/src/test/java/com/box/sdk/BoxFileTest.java +++ b/src/test/java/com/box/sdk/BoxFileTest.java @@ -596,6 +596,65 @@ protected static BoxFile createAndUpdateFileHelper(String fileName, String versi return uploadedFile; } + @Test + @Category(UnitTest.class) + public void canUploadVersionSendsCorrectRequest() { + + BoxAPIConnection api = new BoxAPIConnection(""); + api.setRequestInterceptor(new JSONRequestInterceptor() { + @Override + protected BoxAPIResponse onJSONRequest(BoxJSONRequest request, JsonObject json) { + + Assert.assertEquals("OPTIONS", request.getMethod()); + Assert.assertEquals("/2.0/files/1029/content", request.getUrl().getPath()); + + Assert.assertEquals("foo.txt", json.get("name").asString()); + Assert.assertEquals(1024, json.get("size").asInt()); + return new BoxJSONResponse(200, null, new JsonObject()); + } + }); + BoxFile file = new BoxFile(api, "1029"); + boolean result = file.canUploadVersion("foo.txt", 1024); + + Assert.assertTrue(result); + } + + @Test + @Category(UnitTest.class) + public void canUploadVersionReturnsFalseOnClientError() { + + BoxAPIConnection api = new BoxAPIConnection(""); + api.setRequestInterceptor(new JSONRequestInterceptor() { + @Override + protected BoxAPIResponse onJSONRequest(BoxJSONRequest request, JsonObject json) { + + return new BoxJSONResponse(409, null, new JsonObject()); + } + }); + BoxFile file = new BoxFile(api, "1029"); + boolean result = file.canUploadVersion("foo.txt", 1024); + + Assert.assertFalse(result); + } + + @Test + @Category(UnitTest.class) + public void canUploadVersionReturnsFalseOnServerError() { + + BoxAPIConnection api = new BoxAPIConnection(""); + api.setRequestInterceptor(new JSONRequestInterceptor() { + @Override + protected BoxAPIResponse onJSONRequest(BoxJSONRequest request, JsonObject json) { + + return new BoxJSONResponse(500, null, new JsonObject()); + } + }); + BoxFile file = new BoxFile(api, "1029"); + boolean result = file.canUploadVersion("foo.txt", 1024); + + Assert.assertFalse(result); + } + @Test @Category(IntegrationTest.class) public void getInfoWithOnlyTheNameField() {