Merge branch 'dev'

Release v0.4

Author: gcurtis

README.md

@@ -1,3 +1,5 @@
+[![Project Status](http://opensource.box.com/badges/active.svg)](http://opensource.box.com/badges)
+
 Box Java SDK
 ============
 
@@ -9,18 +11,45 @@ to this SDK.
 Quickstart
 ----------
 
+The SDK can be obtained by either cloning the source into your project, or by
+downloading one of the precompiled JARs from the [releases page on GitHub]
+(https://gitenterprise.inside-box.net/Box/box-java-sdk/releases).
+
+If you use the JAR, you'll also need to include [minimal-json v0.9.1]
+(https://github.com/ralfstx/minimal-json) - which is the SDK's only dependency.
+You can get minimal-json from maven with `com.eclipsesource.minimal-json:minimal-json:0.9.1`.
+
 Here is a simple example of how to authenticate with the API using a developer
 token and then print the ID and name of each item in your root folder.
 
 ```java
 BoxAPIConnection api = new BoxAPIConnection("developer-token");
 BoxFolder rootFolder = BoxFolder.getRootFolder(api);
-for (BoxItem item : rootFolder) {
-    BoxItem.Info info = item.getInfo();
-    System.out.format("[%d] %s\n", item.getID(), info.getName());
+for (BoxItem.Info itemInfo : rootFolder) {
+    System.out.format("[%d] %s\n", itemInfo.getID(), itemInfo.getName());
 }
 ```
 
+### Sample Project
+
+A sample project can be found in `src/example`. This project will output your
+name and a list of the files and folders in your root directory.
+
+To run the project, first provide a developer token in
+`src/example/java/com/box/sdk/example/Main.java`. You can obtain a developer
+token from your application's [developer
+console](https://cloud.app.box.com/developers/services).
+
+```java
+public final class Main {
+    private static final String DEVELOPER_TOKEN = "<YOUR_DEVELOPER_TOKEN>";
+
+    // ...
+}
+```
+
+Then just invoke `gradle runExample` to run the example!
+
 Building
 --------
 
@@ -55,3 +84,20 @@ Javadoc reference documentation is [available here][1]. Javadocs are also
 generated when `gradle javadoc` is run and can be found in `build/doc/javadoc`.
 
 [1]:https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/package-summary.html
+
+Copyright and License
+---------------------
+
+Copyright 2014 Box, Inc. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

build.gradle

@@ -33,6 +33,20 @@ javadoc {
     options.links 'http://docs.oracle.com/javase/8/docs/api/'
 }
 
+sourceSets {
+    example {
+        java {
+            compileClasspath += main.output
+            runtimeClasspath += main.runtimeClasspath
+        }
+    }
+}
+
+task runExample(type: JavaExec, dependsOn: 'exampleClasses') {
+    classpath = sourceSets.example.runtimeClasspath
+    main = 'com.box.sdk.example.Main'
+}
+
 task javadocJar(type: Jar) {
     classifier = 'javadoc'
     from javadoc

doc/overview.md

@@ -54,6 +54,7 @@ BoxUser creator = info.getCreatedBy();
 ### Resource Docs
 
 * [Files](types/files.md)
+* [Folders](types/folders.md)
 
 Requests and Responses
 ----------------------

doc/types/files.md

@@ -5,8 +5,17 @@ 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.).
 
-* [Javadoc Documentation](https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFile.html)
-* [REST API Documentation](https://developers.box.com/docs/#files)
+* [Get a File's Information](#get-a-files-information)
+* [Update a File's Information](#update-a-files-information)
+* [Download a File](#download-a-file)
+* [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)
+* [Upload a New Version of a File](#upload-a-new-version-of-a-file)
+* [Download a Previous Version of a File](#download-a-previous-version-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
 ------------------------

doc/types/folders.md

@@ -0,0 +1,265 @@
+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
+--------------------------
+
+The user's root folder can be accessed with the static
+[`getRootFolder(BoxAPIConnection)`][get-root-folder] method.
+
+```java
+BoxFolder rootFolder = BoxFolder.getRootFolder(api);
+```
+
+[get-root-folder]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getRootFolder(com.box.sdk.BoxAPIConnection)
+
+Get a Folder's Items
+--------------------
+
+Every `BoxFolder` implements [`Iterable<BoxItem>`][iterator] which allows you to
+iterate over the folder's contents. The iterator automatically handles paging
+and will make additional network calls to load more data from Box when
+necessary.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+for (BoxItem.Info itemInfo : folder) {
+    if (itemInfo instanceof BoxFile.Info) {
+        BoxFile.Info fileInfo = (BoxFile.Info) itemInfo;
+        // Do something with the file.
+    } else if (itemInfo instanceof BoxFolder) {
+        BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo;
+        // Do something with the folder.
+    }
+}
+```
+
+`BoxFolder` purposely doesn't provide a way of getting a collection of
+`BoxItems`. Getting the entire contents of a folder is usually unnecessary and
+can be extremely inefficient for folders with a large number of items. If you
+really require a collection instead of an iterable, you can create the
+collection manually.
+
+```java
+Collection<BoxItem> folderItems = new ArrayList<BoxItem>();
+BoxFolder folder = new BoxFolder(api, "id");
+for (BoxItem.Info itemInfo : folder) {
+    folderItems.add(itemInfo.getResource());
+}
+```
+
+[iterator]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#iterator()
+
+Get a Folder's Information
+--------------------------
+
+Calling [`getInfo()`][get-info] on a folder returns a snapshot of the folder's
+info.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+BoxFolder.Info info = folder.getInfo();
+```
+
+Requesting information for only the fields you need can improve performance and
+reduce the size of the network request. The [`getInfo(String...)`][get-info2]
+method lets you specify which fields are retrieved.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+// Only get information about a few specific fields.
+BoxFolder.Info info = folder.getInfo("size", "owned_by");
+```
+
+[get-info]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getInfo()
+[get-info2]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getInfo(java.lang.String...)
+
+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
+[`updateInfo(BoxFolder.Info)`][update-info].
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+BoxFolder.Info info = folder.new Info();
+info.setName("New Name");
+folder.updateInfo(info);
+```
+
+[update-info]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#updateInfo(com.box.sdk.BoxFolder.Info)
+
+Create a Folder
+---------------
+
+Create a child folder by calling [`createFolder(String)`][create-folder] on the
+parent folder.
+
+```java
+BoxFolder parentFolder = new BoxFolder(api, "id");
+BoxFolder.Info childFolderInfo = parentFolder.createFolder("Child Folder Name");
+```
+
+[create-folder]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createFolder(java.lang.String)
+
+Copy a Folder
+-------------
+
+Call the [`copy(BoxFolder)`][copy] method to copy a folder to another folder.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id1");
+BoxFolder destination = new BoxFolder(api, "id2");
+folder.copy(destination);
+```
+
+You can also use the [`copy(BoxFolder, String)`][copy2] method to rename the
+folder while copying it. This allows you to make a copy of the folder in the
+same parent folder, but with a different name.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id1");
+BoxFolder.Info parentFolderInfo = folder.getInfo().getParent();
+BoxFolder parentFolder = parentFolderInfo.getResource();
+folder.copy(parentFolder, "New Name");
+```
+
+[copy]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#copy(com.box.sdk.BoxFolder)
+[copy2]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#copy(com.box.sdk.BoxFolder,%20java.lang.String)
+
+Move a Folder
+-------------
+
+Call the [`move(BoxFolder)`][move] method with the destination you want the folder moved
+to.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id1");
+BoxFolder destination = new BoxFolder(api, "id2");
+folder.move(destination);
+```
+
+[move]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#move(com.box.sdk.BoxFolder)
+
+Rename a Folder
+---------------
+
+Call the [`rename(String)`][rename] method with a new name for the folder.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+folder.rename("New Name");
+```
+
+A folder can also be renamed by updating the folder's information. This is
+useful if you want to perform more than one change to the folder in a single API
+request.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+BoxFolder.Info info = folder.new Info();
+info.setName("New Name");
+folder.updateInfo(info);
+```
+
+[rename]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#rename(java.lang.String)
+
+Delete a Folder
+---------------
+
+A folder can be deleted with the [`delete(boolean)`][delete] method. Passing
+true to this method indicates that the folder and its contents should be
+recursively deleted.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+folder.delete(true);
+```
+
+[delete]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#delete(boolean)
+
+Created a Shared Link for a Folder
+----------------------------------
+
+You can get a shared link for a folder by calling the
+[`createSharedLink(BoxSharedLink.Access, Date, BoxSharedLink.Permissions)`]
+[create-shared-link] method.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+SharedLink link = folder.createSharedLink(BoxSharedLink.Access.OPEN, null,
+    permissions);
+```
+
+A shared link can also be created by updating the folder's information. This is
+useful if you want to perform more than one change to the folder in a single API
+request.
+
+```java
+BoxSharedLink sharedLink = new BoxSharedLink();
+sharedLink.setAccess(BoxSharedLink.Access.OPEN);
+
+BoxFolder folder = new BoxFolder(api, "id");
+BoxFolder.Info info = folder.new Info();
+info.setSharedLink(sharedLink);
+folder.updateInfo(info);
+```
+
+[create-shared-link]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createSharedLink(com.box.sdk.BoxSharedLink.Access,%20java.util.Date,%20com.box.sdk.BoxSharedLink.Permissions)
+
+Share a Folder
+--------------
+
+You can invite another person to collaborate on a folder with the
+[`collaborate(String, BoxCollaboration.Role)`][collaborate] method.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+BoxCollaboration.Info collabInfo = folder.collaborate("[email protected]",
+    BoxCollaboration.Role.EDITOR);
+```
+
+If you already know the user's ID, you can invite them directly without needing
+to know their email address with the
+[`collaborate(BoxCollaborator, BoxCollaboration.Role)`][collaborate2] method.
+
+```java
+BoxUser collaborator = new User(api, "user-id");
+BoxFolder folder = new BoxFolder(api, "folder-id");
+BoxCollaboration.Info collabInfo = folder.collaborate(collaborator,
+    BoxCollaboration.Role.EDITOR);
+```
+
+[collaborate]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#collaborate(java.lang.String,%20com.box.sdk.BoxCollaboration.Role)
+[collaborate2]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#collaborate(com.box.sdk.BoxCollaborator,%20com.box.sdk.BoxCollaboration.Role)
+
+Get All Collaborations for a Folder
+-----------------------------------
+
+The [`getCollaborations()`][get-collaborations] method will return a collection
+of `BoxCollaboration.Info` objects for a folder.
+
+```java
+BoxFolder folder = new BoxFolder(api, "id");
+Collection<BoxCollaboration.Info> collaborations = folder.getCollaborations();
+```
+
+[get-collaborations]: https://gitenterprise.inside-box.net/pages/Box/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getCollaborations()