Add missing methods and documentation

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<BoxCollaboration.Info> 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<BoxCollaboration.Info> 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
 --------------------------
 

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<Representation> 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

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-

src/main/java/com/box/sdk/BoxFile.java

@@ -518,7 +518,9 @@ public Collection<BoxFileVersion> 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<BoxCollaboration.Info> 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<BoxCollaboration.Info> getAllFileCollaborations(String... fields) {
-        return BoxCollaboration.getAllFileCollaborations(this.getAPI(), this.getID(),
-                GET_COLLABORATORS_PAGE_SIZE, fields);
-
-    }
 }

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;