Merge pull request #70 from dp3000/add-support-for-bookmarks

Add support for bookmarks

Author: dp3000

doc/files.md

@@ -1,21 +1,19 @@
-Files
-=====
+# Files
 
 File objects represent individual files in Box. They can be used to download a
 file's contents, upload new versions, and perform other common file operations
 (move, copy, delete, etc.).
 
-* [Get a File's Information](#get-a-files-information)
-* [Update a File's Information](#update-a-files-information)
-* [Upload a File](#upload-a-file)
-* [Copy a File](#copy-a-file)
-* [Delete a File](#delete-a-file)
-* [Get Previous Versions of a File](#get-previous-versions-of-a-file)
-* [Promote a Previous Version of a File](#promote-a-previous-version-of-a-file)
-* [Delete a Previous Version of a File](#delete-a-previous-version-of-a-file)
+-   [Get a File's Information](#get-a-files-information)
+-   [Update a File's Information](#update-a-files-information)
+-   [Upload a File](#upload-a-file)
+-   [Copy a File](#copy-a-file)
+-   [Delete a File](#delete-a-file)
+-   [Get Previous Versions of a File](#get-previous-versions-of-a-file)
+-   [Promote a Previous Version of a File](#promote-a-previous-version-of-a-file)
+-   [Delete a Previous Version of a File](#delete-a-previous-version-of-a-file)
 
-Get a File's Information
-------------------------
+## Get a File's Information
 
 Calling `getFileInfo()` on a file returns a snapshot of the file's info.
 
@@ -24,24 +22,22 @@ BoxFile file = new BoxFile(api, 'file-id');
 BoxFile.Info info = file.getFileInfo();
 ```
 
-Update a File's Information
----------------------------
+## Update a File's Information
 
 Updating a file's information is done by creating a new `BoxFile.Info`
 object or updating an existing one, and then calling `updateFileInfo(BoxFile.Info)`.
 
 ```java
 BoxFile file = new BoxFile(api, 'file-id');
-BoxFile.Info info = new BoxFile.Info();
+BoxFile.Info info = file.getFileInfo();
 info.addValue('name', 'New_File_Name.jpg');
 BoxFile.Info newFileInfo = file.updateFileInfo(info);
 ```
 
-Upload a File
--------------
+## Upload a File
 
 Files are uploaded to a folder by calling either the `uploadFile(Attachment, String)`
-or `uploadFile(Document, String)` method.  If the `newName` String parameter is blank,
+or `uploadFile(Document, String)` method. If the `newName` String parameter is blank,
 the name of the Attachment or Document is used.
 
 ```java
@@ -54,8 +50,7 @@ Upload progress can be tracked by providing the size of the file and a
 [`uploadFile(InputStream, String, long, ProgressListener)`][upload2]. The
 `ProgressListener` will then receive progress updates as the upload completes.
 
-Copy a File
------------
+## Copy a File
 
 A file can be copied to a new folder and optionally be renamed with the
 `copy(BoxFolder)` and `copy(BoxFolder, String)` methods.
@@ -66,8 +61,7 @@ BoxFile file = new BoxFile(api, 'file-id');
 BoxFile.Info copiedFileInfo = file.copy(rootFolder, 'New Name');
 ```
 
-Delete a File
--------------
+## Delete a File
 
 Calling the `deleteFile()` method will move the file to the user's trash.
 
@@ -76,8 +70,7 @@ BoxFile file = new BoxFile(api, 'file-id');
 file.deleteFile();
 ```
 
-Get a trashed File
-------------------
+## Get a trashed File
 
 Calling the `getTrashedFile()` method will retrieve a trashed file to the user including
 information about when the file was moved to the trash.
@@ -87,8 +80,7 @@ BoxFile file = new BoxFile(api, 'file-id');
 file.getTrashedFile();
 ```
 
-Get Previous Versions of a File
--------------------------------
+## Get Previous Versions of a File
 
 For users with premium accounts, versions of a file can be retrieved with the
 `getVersions()` method.
@@ -98,11 +90,10 @@ BoxFile file = new BoxFile(api, 'file-id');
 list<BoxFileVersion.Info> versions = file.getVersions();
 ```
 
-Promote a Previous Version of a File
-------------------------------------
+## Promote a Previous Version of a File
 
 A previous version of a file can be promoted with the `promoteFileVersion()`
-method to become the current version of the file.  Since the `file_version` object returned
+method to become the current version of the file. Since the `file_version` object returned
 from the Box API doesn't include the File Id, you must set it manually before promoting a
 file version.
 
@@ -114,8 +105,7 @@ firstVersion.setFileId('file-id');
 firstVersion.promoteFileVersion();
 ```
 
-Delete a Previous Version of a File
------------------------------------
+## Delete a Previous Version of a File
 
 A version of a file can be deleted and moved to the trash by calling
 `deleteFileVersion()`. Since the `file_version` object returned

doc/folders.md

@@ -1,25 +1,23 @@
-Folders
-=======
+# Folders
 
 Folder objects represent a folder from a user's account. They can be used to
 iterate through a folder's contents, collaborate a folder with another user or
 group, and perform other common folder operations (move, copy, delete, etc.).
 
-* [Get the User's Root Folder](#get-the-users-root-folder)
-* [Get a Folder's Items](#get-a-folders-items)
-* [Get a Folder's Information](#get-a-folders-information)
-* [Update a Folder's Information](#update-a-folders-information)
-* [Create a Folder](#create-a-folder)
-* [Copy a Folder](#copy-a-folder)
-* [Move a Folder](#move-a-folder)
-* [Rename a Folder](#rename-a-folder)
-* [Delete a Folder](#delete-a-folder)
-* [Created a Shared Link for a Folder](#created-a-shared-link-for-a-folder)
-* [Share a Folder](#share-a-folder)
-* [Get All Collaborations for a Folder](#get-all-collaborations-for-a-folder)
-
-Get the User's Root Folder
---------------------------
+-   [Get the User's Root Folder](#get-the-users-root-folder)
+-   [Get a Folder's Items](#get-a-folders-items)
+-   [Get a Folder's Information](#get-a-folders-information)
+-   [Update a Folder's Information](#update-a-folders-information)
+-   [Create a Folder](#create-a-folder)
+-   [Copy a Folder](#copy-a-folder)
+-   [Move a Folder](#move-a-folder)
+-   [Rename a Folder](#rename-a-folder)
+-   [Delete a Folder](#delete-a-folder)
+-   [Created a Shared Link for a Folder](#created-a-shared-link-for-a-folder)
+-   [Share a Folder](#share-a-folder)
+-   [Get All Collaborations for a Folder](#get-all-collaborations-for-a-folder)
+
+## Get the User's Root Folder
 
 The user's root folder can be accessed with the static
 `getRootFolder(BoxAPIConnection)` method.
@@ -28,12 +26,11 @@ The user's root folder can be accessed with the static
 BoxFolder rootFolder = BoxFolder.getRootFolder(api);
 ```
 
-Get a Folder's Items
---------------------
+## Get a Folder's Items
 
-A call to `getChildren()` will return the contents of a `BoxFolder`.  Optionally, an offset and limit
+A call to `getChildren()` will return the contents of a `BoxFolder`. Optionally, an offset and limit
 can be set to iterate over a large folder. Large folder operations will likely
-fail due to governor limits on callouts or heap size.  This method could be detrimental depending
+fail due to governor limits on callouts or heap size. This method could be detrimental depending
 on your use case.
 
 ```java
@@ -48,8 +45,7 @@ for (BoxItem.Info itemInfo : children) {
 }
 ```
 
-Get a Folder's Information
---------------------------
+## Get a Folder's Information
 
 Calling `getFolderInfo()` on a folder returns a snapshot of the folder's
 info.
@@ -59,22 +55,20 @@ BoxFolder folder = new BoxFolder(api, 'folder-id');
 BoxFolder.Info info = folder.getFolderInfo();
 ```
 
-Update a Folder's Information
------------------------------
+## Update a Folder's Information
 
 Updating a folder's information is done by creating a new `BoxFolder.Info`
 object or updating an existing one, and then calling
 `updateFolderInfo(BoxFolder.Info)`.
 
 ```java
 BoxFolder folder = new BoxFolder(api, 'folder-id');
-BoxFolder.Info info = folder.new Info();
+BoxFolder.Info info = folder.getFolderInfo();
 info.addValue('description', 'Some folder I made');
 folder.updateFolderInfo(info);
 ```
 
-Create a Folder
----------------
+## Create a Folder
 
 Create a child folder by calling `createFolder(String)` on the
 parent folder.
@@ -84,8 +78,7 @@ BoxFolder parentFolder = new BoxFolder(api, 'parent-folder-id');
 BoxFolder.Info childFolderInfo = parentFolder.createFolder('Child Folder Name');
 ```
 
-Copy a Folder
--------------
+## Copy a Folder
 
 Call the `copy(BoxFolder)` method to copy a folder to another folder.
 
@@ -105,8 +98,7 @@ BoxFolder destination = new BoxFolder(api, 'destination-folder-id');
 folder.copy(destination, 'New Folder Name');
 ```
 
-Move a Folder
--------------
+## Move a Folder
 
 Call the `move(BoxFolder)` method with the destination you want the folder moved
 to.
@@ -119,8 +111,7 @@ folder.move(destination);
 
 Similar to the `copy` method, the folder can be renamed by calling `move(BoxFolder, String)`.
 
-Rename a Folder
----------------
+## Rename a Folder
 
 Call the `rename(String)` method with a new name for the folder.
 
@@ -141,8 +132,7 @@ info.addValue('name', 'New Folder Name');
 folder.updateFolderInfo(info);
 ```
 
-Delete a Folder
----------------
+## Delete a Folder
 
 A folder can be deleted with the `deleteFolder(boolean)` method. Passing
 true to this method indicates that the folder and its contents should be
@@ -153,8 +143,7 @@ BoxFolder folder = new BoxFolder(api, 'folder-id');
 folder.deleteFolder(true);
 ```
 
-Created a Shared Link for a Folder
-----------------------------------
+## Created a Shared Link for a Folder
 
 You can get a shared link for a folder by calling the
 `createSharedLink(BoxSharedLink.Access, DateTime, BoxSharedLink.Permissions)` method.
@@ -165,12 +154,11 @@ BoxSharedLink.Permissions permissions = new BoxSharedLink.Permissions();
 BoxSharedLink.Info linkInfo = folder.createSharedLink(BoxSharedLink.Access.OPEN, null, permissions);
 ```
 
-Share a Folder
---------------
+## Share a Folder
 
 You can invite another person to collaborate on a folder with the
 [collaborate(String, BoxCollaboration.Role)` method. The Box user with the email address
-specified will receive a collaboration request.  If the email is not associated with a Box
+specified will receive a collaboration request. If the email is not associated with a Box
 account, an invitation to create a Box account will be sent.
 
 ```java
@@ -188,8 +176,7 @@ BoxFolder folder = new BoxFolder(api, 'folder-id');
 BoxCollaboration.Info collabInfo = folder.collaborate(collaborator, BoxCollaboration.Role.EDITOR);
 ```
 
-Get All Collaborations for a Folder
------------------------------------
+## Get All Collaborations for a Folder
 
 The `getCollaborations()` method will return a list
 of `BoxCollaboration.Info` objects for a folder.

doc/web-links.md

@@ -0,0 +1,55 @@
+# Web Links
+
+Represents a web link (bookmark) on Box
+
+## Get a Web Link's Information
+
+```java
+BoxWebLink webLink = new BoxWebLink(api, 'web-link-id');
+BoxWebLink.Info info = webLink.getWebLinkInfo();
+```
+
+## Create a Web Link
+
+```java
+BoxWebLink webLink = new BoxWebLink(api, null);
+BoxWebLink.Info info = new BoxWebLink.Info('{"url":"https://www.salesforce.com/", "parent": {"id": "0"}, "name": "Salesforce", "description": "Link to Salesforce"}');
+BoxWebLink.Info created = webLink.createWebLink(info);
+```
+
+## Update a Web Link's Information
+
+```java
+BoxWebLink webLink = new BoxWebLink(api, 'web-link-id');
+BoxWebLink.Info info = webLink.getWebLinkInfo();
+info.addValue('description', 'a descriptive description');
+BoxWebLink.Info updated = webLink.updateWebLinkInfo(info);
+```
+
+## Delete a Web Link
+
+```java
+BoxWebLink webLink = new BoxWebLink(api, 'web-link-id');
+webLink.deleteWebLink();
+```
+
+## Get a Trashed Web Link's Information
+
+```java
+BoxWebLink webLink = new BoxWebLink(api, 'web-link-id');
+BoxWebLink.Info info = webLink.getTrashedWebLinkInfo();
+```
+
+## Restore a Trashed Web Link
+
+```java
+BoxWebLink webLink = new BoxWebLink(api, 'web-link-id');
+BoxWebLink.Info info = webLink.restoreTrashedWebLink();
+```
+
+## Permanently Delete a Web Link
+
+```java
+BoxWebLink webLink = new BoxWebLink(api, 'web-link-id');
+webLink.permanentlyDeleteWebLink();
+```

src/classes/BoxFolderTests.cls

@@ -101,14 +101,14 @@ public class BoxFolderTests {
 
     public static testMethod void testGetObjectType() {
         BoxApiConnection api = new BoxApiConnection('accesstoken');
-        BoxFolder folder = new BoxFolder(api, 'folderid');
+        BoxFolder folder = new BoxFolder(api, '11446498');
         System.assertEquals('folder', folder.getObjectType());
     }
 
     public static testMethod void testSetInfo() {
         String mockResponseBody = '{"type":"folder","id":"11446498","sequence_id":"1","etag":"1","name":"Pictures","created_at":"2012-12-12T10:53:43-08:00","modified_at":"2012-12-12T11:15:04-08:00","description":"Some pictures I took","size":629644,"path_collection":{"total_count":1,"entries":[{"type":"folder","id":"0","sequence_id":null,"etag":null,"name":"All Files"}]},"created_by":{"type":"user","id":"17738362","name":"sean rose","login":"[email protected]"},"modified_by":{"type":"user","id":"17738362","name":"sean rose","login":"[email protected]"},"owned_by":{"type":"user","id":"17738362","name":"sean rose","login":"[email protected]"},"shared_link":{"url":"https://www.box.com/s/vspke7y05sb214wjokpk","download_url":null,"vanity_url":null,"is_password_enabled":false,"unshared_at":null,"download_count":0,"preview_count":0,"access":"open","permissions":{"can_download":true,"can_preview":true}},"folder_upload_email":{"access":"open","email":"[email protected]"},"parent":{"type":"folder","id":"0","sequence_id":null,"etag":null,"name":"All Files"},"item_status":"active","item_collection":{"total_count":1,"entries":[{"type":"file","id":"5000948880","sequence_id":"3","etag":"3","sha1":"134b65991ed521fcfe4724b7d814ab8ded5185dc","name":"tigers.jpeg"}],"offset":0,"limit":100}}';
         BoxApiConnection api = new BoxApiConnection('accesstoken');
-        BoxFolder folder = new BoxFolder(api, 'All Files');
+        BoxFolder folder = new BoxFolder(api, '11446498');
         BoxFolder.Info subfolderInfo = new BoxFolder.Info(mockResponseBody);
         BoxFolder.Info parentFolderInfo = new BoxFolder.Info(
             subfolderInfo.getValue('parent')

src/classes/BoxResource.cls

@@ -21,6 +21,7 @@ public abstract class BoxResource {
      */
     public BoxResource(BoxApiConnection api, String id) {
         this.api = api;
+        validateId(id);
         this.id = id;
     }
 
@@ -96,6 +97,20 @@ public abstract class BoxResource {
         return (BoxResource.Info) information;
     }
 
+    /**
+     * Validates the ID of this resource.
+     *
+     * @return void
+     */
+    private void validateId(String id) {
+        if (String.isNotEmpty(id)) {
+            System.assert(
+                id.isNumeric(),
+                'Expect resource to be constructed with a numeric ID'
+            );
+        }
+    }
+
     public abstract void setInfo(BoxJsonObject jsonObject);
 
     public abstract String getObjectType();