Merge branch 'dev'

Release v0.3

CONTRIBUTING.md

@@ -0,0 +1,108 @@
+Contributing
+============
+
+All contributions are welcome to this project.
+
+Contributor License Agreement
+-----------------------------
+
+Before a contribution can be merged into this project, please fill out the
+Contributor License Agreement (CLA) located at:
+
+http://opensource.box.com/cla
+
+To learn more about CLAs and why they are important to open source projects,
+please see the [Wikipedia entry][1].
+
+How to contribute
+-----------------
+
+* **File an issue** - if you found a bug, want to request an enhancement, or
+  want to implement something (bug fix or feature).
+* **Send a pull request** - if you want to contribute code. Please be sure to
+  file an issue first.
+
+Pull request best practices
+---------------------------
+
+Following these steps will help ensure that your pull request gets reviewed and
+accepted as quickly as possible.
+
+### Step 1: File an issue
+
+Before writing any code, please file an issue stating the problem you want to
+solve or the feature you want to implement. This allows us to give you feedback
+before you spend any time writing code. There may be a known limitation that
+can't be addressed, or a bug that has already been fixed in a different way. The
+issue allows us to communicate and figure out if it's worth your time to write a
+bunch of code for the project.
+
+### Step 2: Fork this repository in GitHub
+
+This will create your own copy of our repository.
+
+### Step 3: Add the upstream source
+
+The upstream source is the project under the Box organization on GitHub. To add
+an upstream source for this project, type:
+
+```
+git remote add upstream [email protected]:box/box-java-sdk.git
+```
+
+This will come in useful later.
+
+### Step 4: Create a feature branch
+
+Create a branch with a descriptive name, such as `add-search`.
+
+### Step 5: Push your feature branch to your fork
+
+As you develop code, continue to push code to your remote feature branch. Please
+make sure to include the issue number you're addressing in the body of your
+commit message and adhere to [standard git commit message guidelines][2]. For
+example:
+
+```
+Add search
+
+Introduced a new BoxSearch class that uses the /search API endpoint.
+
+Closes #123.
+```
+
+This helps us out by allowing us to track which issue your commit relates to.
+
+Keep a separate feature branch for each issue you want to address.
+
+### Step 6: Rebase
+
+Before sending a pull request, rebase against upstream, such as:
+
+```
+git fetch upstream
+git rebase upstream/master
+```
+
+This will add your changes on top of what's already in upstream, minimizing
+merge issues.
+
+### Step 7: Build and test your changes
+
+Make sure that the code builds and passes all unit tests by running:
+
+```bash
+$ gradle clean build
+```
+
+### Step 8: Send the pull request
+
+Send the pull request from your feature branch to us. Be sure to include a
+description in your commit message (not the pull request description) that lets
+us know what work you did.
+
+Keep in mind that we like to see one issue addressed per pull request, as this
+helps keep our git history clean and we can more easily track down issues.
+
+[1]: http://en.wikipedia.org/wiki/Contributor_License_Agreement
+[2]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

build.gradle

@@ -18,8 +18,19 @@ dependencies {
     testCompile 'org.slf4j:slf4j-nop:1.7.7'
 }
 
-tasks.withType(JavaCompile) {
-    options.compilerArgs << '-Xlint:all'
+javadoc {
+    options.windowTitle 'Box Java SDK'
+    options.noQualifiers 'all'
+    options.stylesheetFile file('doc/css/javadoc.css')
+    options.noTree true
+    options.noIndex true
+    options.noHelp true
+    options.noDeprecatedList true
+    options.noNavBar true
+    options.docEncoding 'utf-8'
+    options.charSet 'utf-8'
+    options.linkSource true
+    options.links 'http://docs.oracle.com/javase/8/docs/api/'
 }
 
 task javadocJar(type: Jar) {
@@ -32,8 +43,19 @@ task sourcesJar(type: Jar) {
     from sourceSets.main.allSource
 }
 
-artifacts {
-    archives sourcesJar, javadocJar
+task integrationTest(type: Test) {
+    description 'Runs the integration tests.'
+    group 'Verification'
+
+    useJUnit {
+        includeCategories 'com.box.sdk.IntegrationTest'
+    }
+}
+
+jacocoTestReport.dependsOn(integrationTest);
+
+tasks.withType(JavaCompile) {
+    options.compilerArgs << '-Xlint:all'
 }
 
 tasks.withType(Test) {
@@ -48,32 +70,12 @@ tasks.withType(Test) {
     }
 }
 
-test {
-    useJUnit {
-        excludeCategories 'com.box.sdk.IntegrationTest'
-    }
+artifacts {
+    archives sourcesJar, javadocJar
 }
 
-task integrationTest(type: Test) {
-    description 'Runs the integration tests.'
-    group 'Verification'
-
+test {
     useJUnit {
-        includeCategories 'com.box.sdk.IntegrationTest'
+        excludeCategories 'com.box.sdk.IntegrationTest'
     }
 }
-
-javadoc {
-    options.windowTitle 'Box Java SDK'
-    options.noQualifiers 'all'
-    options.stylesheetFile file('doc/css/javadoc.css')
-    options.noTree true
-    options.noIndex true
-    options.noHelp true
-    options.noDeprecatedList true
-    options.noNavBar true
-    options.docEncoding 'utf-8'
-    options.charSet 'utf-8'
-    options.linkSource true
-    options.links 'http://docs.oracle.com/javase/8/docs/api/'
-}

doc/css/javadoc.css

@@ -217,7 +217,6 @@ div.summary ul.blockList li.blockList ul.blockList li.blockList ul.blockList li.
     position: relative;
 }
 .indexContainer {
-    background-color: rgb(64, 64, 64);
     margin: 10px;
     position: relative;
     font-size: 1.0em;

doc/overview.md

@@ -5,8 +5,8 @@ This guide covers the basics behind the various components of the Box Java SDK.
 It's also recommended that you take a look at [the
 documentation](https://developers.box.com/docs/) for the Box API.
 
-API Connections
----------------
+Authentication
+--------------
 
 The first step in using the SDK is always authenticating and connecting to the
 API. The SDK does this through the `BoxAPIConnection` class. This class
@@ -24,28 +24,6 @@ a connection for each user if your application supports multiple user accounts.
 See the [Authentication guide](authentication.md) for details on how to create
 and use `BoxAPIConnection`.
 
-Requests and Responses
-----------------------
-
-All communication with Box's API is done through `BoxAPIRequest` and
-`BoxAPIResponse` (or their subclasses). These classes handle all the dirty work
-of setting appropriate headers, handling errors, and sending/receiving data.
-
-You generally won't need to use these classes directly, as the resource types
-are easier and cover most use-cases. However, these classes are extremely
-flexible and can be used if you need to make custom API calls.
-
-Here's an example using `BoxAPIRequest` and `BoxJSONResponse` that gets a list
-of items with some custom fields:
-
-```java
-BoxAPIConnection api = new BoxAPIConnection("token");
-URL url = new URL("https://api.box.com/2.0/folders/0/items?fields=name,created_at")
-BoxAPIRequest request = new BoxAPIRequest(api, url, "GET");
-BoxJSONResponse response = (BoxJSONResponse) request.send();
-String json = response.getJSON();
-```
-
 Resource Types
 --------------
 
@@ -72,3 +50,29 @@ BoxFolder.Info info = folder.getInfo();
 // This BoxUser has the same BoxAPIConnection as "folder".
 BoxUser creator = info.getCreatedBy();
 ```
+
+### Resource Docs
+
+* [Files](types/files.md)
+
+Requests and Responses
+----------------------
+
+All communication with Box's API is done through `BoxAPIRequest` and
+`BoxAPIResponse` (or their subclasses). These classes handle all the dirty work
+of setting appropriate headers, handling errors, and sending/receiving data.
+
+You generally won't need to use these classes directly, as the resource types
+are easier and cover most use-cases. However, these classes are extremely
+flexible and can be used if you need to make custom API calls.
+
+Here's an example using `BoxAPIRequest` and `BoxJSONResponse` that gets a list
+of items with some custom fields:
+
+```java
+BoxAPIConnection api = new BoxAPIConnection("token");
+URL url = new URL("https://api.box.com/2.0/folders/0/items?fields=name,created_at")
+BoxAPIRequest request = new BoxAPIRequest(api, url, "GET");
+BoxJSONResponse response = (BoxJSONResponse) request.send();
+String json = response.getJSON();
+```