Skip to content

Commit e66052f

Browse files
author
Stephen Cobbe
committed
Update README.
1 parent ce883f4 commit e66052f

File tree

1 file changed

+132
-22
lines changed

1 file changed

+132
-22
lines changed

‎ReadMe.md

Lines changed: 132 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ A Java library to access [Dropbox's HTTP-based Core API v2](https://www.dropbox.
44

55
License: [MIT](License.txt)
66

7-
[Javadoc.](https://dropbox.github.io/dropbox-sdk-java/api-docs/v3.0.x/)
7+
Documentation: [Javadocs](https://dropbox.github.io/dropbox-sdk-java/api-docs/v3.0.x/)
88

99
## Setup
1010

@@ -29,34 +29,144 @@ dependencies {
2929

3030
You can also download the Java SDK JAR and and its required dependencies directly from the [latest release page](https://github.com/dropbox/dropbox-sdk-java/releases/latest). Note that the distribution artifacts on the releases pages do not contain optional dependencies.
3131

32-
## Get a Dropbox API key
32+
## Dropbox for Java tutorial
3333

34-
You need a Dropbox API key to make API requests.
35-
* Go to: [https://www.dropbox.com/developers/apps](https://www.dropbox.com/developers/apps)
36-
* If you've already registered an app, click on the "Options" link to see the app's API key and secret.
37-
* Otherwise, click "Create an app" to register an app. Choose "Dropbox API app", then "Files and datastores", then "Yes" or "No" [depending on your needs](https://www.dropbox.com/developers/reference#permissions).
34+
A good way to start using the Java SDK is to follow this quick tutorial. Just make sure you have the the Java SDK [installed](/developers/documentation/java#install) first!
3835

39-
Save the API key to a JSON file called, say, "test.app":
36+
### Register a Dropbox API app
4037

38+
To use the Dropbox API, you'll need to register a new app in the [App Console](/developers/apps). Select Dropbox API app and choose your app's permission. You'll need to use the app key created with this app to access API v2.
39+
40+
### Link an account
41+
42+
In order to make calls to the API, you'll need an instance of the Dropbox object. To instantiate, pass in the access token for the account you want to link. (Tip: You can [generate an access token](https://blogs.dropbox.com/developers/2014/05/generate-an-access-token-for-your-own-account/) for your own account through the [App Console](https://www.dropbox.com/developers/apps)).
43+
44+
```java
45+
import com.dropbox.core.DbxRequestConfig;
46+
import com.dropbox.core.v2.DbxClientV2;
47+
48+
public class Main {
49+
private static final String ACCESS_TOKEN = "<ACCESS TOKEN>";
50+
51+
public static void main(String args[]) throws DbxException {
52+
// Create Dropbox client
53+
DbxRequestConfig config = new DbxRequestConfig("dropbox/java-tutorial", "en_US");
54+
DbxClientV2 client = new DbxClientV2(config, ACCESS_TOKEN);
55+
}
56+
}
4157
```
42-
{
43-
"key": "Your Dropbox API app key",
44-
"secret": "Your Dropbox API app secret"
58+
59+
Test it out to make sure you've linked the right account:
60+
61+
```java
62+
// Get current account info
63+
FullAccount account = client.users().getCurrentAccount();
64+
System.out.println(account.getName().getDisplayName());
65+
```
66+
67+
### Try some API requests
68+
69+
You can use the Dropbox object you instantiated above to make API calls. Try out a request to list the contents of a folder.
70+
71+
```java
72+
// Get files and folder metadata from Dropbox root directory
73+
ListFolderResult result = client.files().listFolder("");
74+
while (true) {
75+
for (Metadata metadata : result.getEntries()) {
76+
System.out.println(metadata.getPathLower());
77+
}
78+
79+
if (!result.getHasMore()) {
80+
break;
81+
}
82+
83+
result = client.files().listFolderContinue(result.getCursor());
84+
}
85+
```
86+
87+
Try uploading a file to your Dropbox.
88+
89+
```java
90+
// Upload "test.txt" to Dropbox
91+
try (InputStream in = new FileInputStream("test.txt")) {
92+
FileMetadata metadata = client.files().uploadBuilder("/test.txt")
93+
.uploadAndFinish(in);
94+
}
95+
```
96+
97+
### Full Example Snippet
98+
99+
```java
100+
import com.dropbox.core.DbxException;
101+
import com.dropbox.core.DbxRequestConfig;
102+
import com.dropbox.core.v2.DbxClientV2;
103+
import com.dropbox.core.v2.files.FileMetadata;
104+
import com.dropbox.core.v2.files.ListFolderResult;
105+
import com.dropbox.core.v2.files.Metadata;
106+
import com.dropbox.core.v2.users.FullAccount;
107+
108+
import java.util.List;
109+
110+
import java.io.FileInputStream;
111+
import java.io.InputStream;
112+
import java.io.IOException;
113+
114+
public class Main {
115+
private static final String ACCESS_TOKEN = "<ACCESS TOKEN>";
116+
117+
public static void main(String args[]) throws DbxException, IOException {
118+
// Create Dropbox client
119+
DbxRequestConfig config = new DbxRequestConfig("dropbox/java-tutorial", "en_US");
120+
DbxClientV2 client = new DbxClientV2(config, ACCESS_TOKEN);
121+
122+
// Get current account info
123+
FullAccount account = client.users().getCurrentAccount();
124+
System.out.println(account.getName().getDisplayName());
125+
126+
// Get files and folder metadata from Dropbox root directory
127+
ListFolderResult result = client.files().listFolder("");
128+
while (true) {
129+
for (Metadata metadata : result.getEntries()) {
130+
System.out.println(metadata.getPathLower());
131+
}
132+
133+
if (!result.getHasMore()) {
134+
break;
135+
}
136+
137+
result = client.files().listFolderContinue(result.getCursor());
138+
}
139+
140+
// Upload "test.txt" to Dropbox
141+
try (InputStream in = new FileInputStream("test.txt")) {
142+
FileMetadata metadata = client.files().uploadBuilder("/test.txt")
143+
.uploadAndFinish(in);
144+
}
145+
}
45146
}
46147
```
47148

48-
## Using the Dropbox API
149+
## Full examples
49150

50-
Before your app can access a Dropbox user's files, the user must authorize your application using OAuth 2. Successfully completing this authorization flow gives you an _access token_ for the user's Dropbox account, which grants you the ability to make Dropbox API calls to access their files.
151+
Some more complete examples can be found here:
51152
* Example for a simple web app: [Web File Browser example](examples/web-file-browser/src/main/java/com/dropbox/core/examples/web_file_browser/DropboxAuth.java)
52153
* Example for an Android app: [Android example](examples/android/src/main/java/com/dropbox/core/examples/android/UserActivity.java)
53154
* Example for a command-line tool: [Command-Line Authorization example](examples/authorize/src/main/java/com/dropbox/core/examples/authorize/Main.java)
54155

55-
Once you have an access token, create a [`DbxClientV2`](https://dropbox.github.io/dropbox-sdk-java/api-docs/v2.1.x/com/dropbox/core/v2/DbxClientV2.html) and start making API calls.
156+
To try out running this examples, please follow the instructions below.
56157

57-
You only need to perform the authorization process once per user. Once you have an access token for a user, save it somewhere persistent, like in a database. The next time that user visits your app's, you can skip the authorization process and go straight to creating a `DbxClientV2` and making API calls.
158+
### Save your Dropbox API key
159+
160+
Save your Dropbox API key to a JSON file called, say, "test.app":
161+
162+
```
163+
{
164+
"key": "Your Dropbox API app key",
165+
"secret": "Your Dropbox API app secret"
166+
}
167+
```
58168

59-
## Building from source
169+
### Building from source
60170

61171
```
62172
git clone https://github.com/dropbox/dropbox-sdk-java.git
@@ -67,15 +177,15 @@ cd dropbox-sdk-java
67177

68178
The output will be in "build/".
69179

70-
## Running the examples
180+
### Running the examples
71181

72182
1. Follow the instructions in the "Build from source" section above.
73183
2. Save your Dropbox API key in a file called "test.app". See: [Get a Dropbox API key](#get-a-dropbox-api-key), above.
74184
3. Compile and install the SDK into your local maven repo: `./gradlew install`
75185
4. To compile all the examples: `(cd examples/ && ./gradlew classes`
76186
5. To compile just one example: `(cd examples/ && ./gradlew :<example-name>:classes`
77187

78-
### authorize
188+
#### authorize
79189

80190
This examples runs through the OAuth 2 authorization flow.
81191

@@ -86,7 +196,7 @@ cd examples
86196

87197
This produces a file named "test.auth" that has the access token. This file can be passed in to the other examples.
88198

89-
### account-info
199+
#### account-info
90200

91201
A simple example that fetches and displays information about the account associated with the access token.
92202

@@ -97,7 +207,7 @@ cd examples
97207

98208
(You must first generate "test.auth" using the "authorize" example above.)
99209

100-
### longpoll
210+
#### longpoll
101211

102212
An example of how to watch for changes in a Dropbox directory.
103213

@@ -108,11 +218,11 @@ cd examples
108218

109219
(You must first generate "test.auth" using the "authorize" example above.)
110220

111-
### tutorial
221+
#### tutorial
112222

113223
The example from our [online tutorial](https://www.dropbox.com/developers/documentation/java#tutorial). Unlike the other examples, this example is not meant to be run without modification.
114224

115-
### upload-file
225+
#### upload-file
116226

117227
Uploads a file to Dropbox. The example includes regular and chunked file uploads.
118228

@@ -123,7 +233,7 @@ cd examples
123233

124234
(You must first generate "test.auth" using the "authorize" example above.)
125235

126-
### web-file-browser
236+
#### web-file-browser
127237

128238
A tiny web app that runs through the OAuth 2 authorization flow and then uses Dropbox API calls to let the user browse their Dropbox files.
129239

0 commit comments

Comments
 (0)