Skip to content

Commit 3ea3509

Browse files
lpatino10lpatino10
authored
Merge pull request #1045 from watson-developer-cloud/async-readme
Add information about using new async library
2 parents d52d773 + 5783d12 commit 3ea3509

File tree

1 file changed

+85
-117
lines changed

1 file changed

+85
-117
lines changed

‎README.md

Lines changed: 85 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,13 @@ Java client library to use the [Watson APIs][wdc].
2020
* [IAM](#iam)
2121
* [Username and password](#username-and-password)
2222
* [API key](#api-key)
23+
* [Using the SDK](#using-the-sdk)
24+
* [Configuring the HTTP client](#configuring-the-http-client)
25+
* [Making asynchronous API calls](#making-asynchronous-api-calls)
26+
* [Default headers](#default-headers)
27+
* [Sending request headers](#sending-request-headers)
28+
* [Parsing HTTP response info](#parsing-http-response-info)
29+
* [FAQ](#faq)
2330
* IBM Watson Services
2431
* [Assistant](assistant)
2532
* [Compare and Comply](compare-comply)
@@ -34,13 +41,6 @@ Java client library to use the [Watson APIs][wdc].
3441
* [Tradeoff Analytics](tradeoff-analytics)
3542
* [Visual Recognition](visual-recognition)
3643
* [Android](#android)
37-
* [Configuring the HTTP client](#configuring-the-http-client)
38-
* [Default headers](#default-headers)
39-
* [Sending request headers](#sending-request-headers)
40-
* [Parsing HTTP response info](#parsing-http-response-info)
41-
* [Specifying a service URL](#specifying-a-service-url)
42-
* [401 unauthorized error](#401-unauthorized-error)
43-
* [Changes for v4.0](#changes-for-v40)
4444
* [Debug](#debug)
4545
* [Eclipse and Intellij](#working-with-eclipse-and-intellij-idea)
4646
* [License](#license)
@@ -92,29 +92,6 @@ Only Assistant:
9292
'com.ibm.watson.developer_cloud:assistant:6.14.0'
9393
```
9494

95-
##### Development snapshots
96-
97-
Snapshots of the development version are available in [Sonatype's snapshots repository][sonatype_snapshots].
98-
99-
###### Gradle
100-
101-
Add repository to your project Gradle file
102-
103-
```gradle
104-
allprojects {
105-
repositories {
106-
maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
107-
}
108-
}
109-
```
110-
111-
And then reference the snapshot version on your app module gradle
112-
Only Speech to Text:
113-
114-
```gradle
115-
'com.ibm.watson.developer_cloud:speech-to-text:6.14.1-SNAPSHOT'
116-
```
117-
11895
##### JAR
11996

12097
Download the jar with dependencies [here][jar].
@@ -252,11 +229,9 @@ Discovery service = new Discovery("2017-11-07");
252229
service.setUsernameAndPassword("<username>", "<password>");
253230
```
254231

255-
## Android
232+
## Using the SDK
256233

257-
The Android SDK utilizes the Java SDK while making some Android-specific additions. This repository can be found [here](https://github.com/watson-developer-cloud/android-sdk). It depends on [OkHttp][] and [gson][].
258-
259-
## Configuring the HTTP client
234+
### Configuring the HTTP client
260235

261236
The HTTP client can be configured by using the `configureClient()` method on your service object, passing in an `HttpConfigOptions` object. Currently, the following options are supported:
262237
- Disabling SSL verification (only do this if you really mean to!) ⚠️
@@ -276,7 +251,71 @@ HttpConfigOptions options = new HttpConfigOptions.Builder()
276251
service.configureClient(options);
277252
```
278253

279-
## Sending request headers
254+
### Making asynchronous API calls
255+
256+
The basic, synchronous way to make API calls with this SDK is through the use of the `execute()` method. Using this method looks something like this:
257+
```java
258+
// make API call
259+
ListEnvironmentsResponse response = service.listEnvironments().execute();
260+
261+
// continue execution
262+
```
263+
264+
However, if you need to perform these calls in the background, there are two other main methods to do this asynchronously: `enqueue()` and `reactiveRequest()`.
265+
266+
#### `enqueue()`
267+
268+
This method allows you to set a callback for the service response through the use of the `ServiceCallback` object. Here's an example:
269+
```java
270+
// make API call in the background
271+
service.listEnvironments().enqueue(new ServiceCallback<ListEnvironmentsResponse>() {
272+
@Override
273+
public void onResponse(ListEnvironmentsResponse response) {
274+
System.out.println("We did it! " + response);
275+
}
276+
277+
@Override
278+
public void onFailure(Exception e) {
279+
System.out.println("Whoops...");
280+
}
281+
});
282+
283+
// continue working in the meantime!
284+
```
285+
286+
#### `reactiveRequest()`
287+
288+
If you're a fan of the [RxJava](https://github.com/ReactiveX/RxJava) library, this method lets you leverage that to allow for "reactive" programming. The method will return a `Single<T>` which you can manipulate how you please. Example:
289+
```java
290+
// get stream with request
291+
Single<ListEnvironmentsResponse> observableRequest = service.listEnvironments().reactiveRequest();
292+
293+
// make API call in the background
294+
observableRequest
295+
.subscribeOn(Schedulers.single())
296+
.subscribe(response -> System.out.println("We did it with s~t~r~e~a~m~s! " + response));
297+
298+
// continue working in the meantime!
299+
```
300+
301+
### Default headers
302+
303+
Default headers can be specified at any time by using the `setDefaultHeaders(Map<String, String> headers)` method.
304+
305+
The example below sends the `X-Watson-Learning-Opt-Out` header in every request preventing Watson from using the payload to improve the service.
306+
307+
```java
308+
PersonalityInsights service = new PersonalityInsights("2016-10-19");
309+
310+
Map<String, String> headers = new HashMap<String, String>();
311+
headers.put(HttpHeaders.X_WATSON_LEARNING_OPT_OUT, "true");
312+
313+
service.setDefaultHeaders(headers);
314+
315+
// All the api calls from now on will send the default headers
316+
```
317+
318+
### Sending request headers
280319

281320
Custom headers can be passed with any request. To do so, add the header to the `ServiceCall` object before executing the request. For example, this is what it looks like to send the header `Custom-Header` along with a call to the Watson Assistant service:
282321

@@ -286,7 +325,7 @@ WorkspaceCollection workspaces = service.listWorkspaces()
286325
.execute();
287326
```
288327

289-
## Parsing HTTP response info
328+
### Parsing HTTP response info
290329

291330
The basic `execute()`, `enqueue()`, and `rx()` methods make HTTP requests to your Watson service and return models based on the requested endpoint. If you would like access to some HTTP response information along with the response model, you can use the more detailed versions of those three methods: `executeWithDetails()`, `enqueueWithDetails()`, and `rxWithDetails()`. To capture the responses, use the new `Response<T>` class, with `T` being the expected response model.
292331

@@ -317,42 +356,13 @@ service.listWorkspaces().enqueueWithDetails(new ServiceCallbackWithDetails<Works
317356
});
318357
```
319358

320-
## Default headers
321-
322-
Default headers can be specified at any time by using the `setDefaultHeaders(Map<String, String> headers)` method.
323-
324-
The example below sends the `X-Watson-Learning-Opt-Out` header in every request preventing Watson from using the payload to improve the service.
325-
326-
```java
327-
PersonalityInsights service = new PersonalityInsights("2016-10-19");
328-
329-
Map<String, String> headers = new HashMap<String, String>();
330-
headers.put(HttpHeaders.X_WATSON_LEARNING_OPT_OUT, "true");
331-
332-
service.setDefaultHeaders(headers);
333-
334-
// All the api calls from now on will send the default headers
335-
```
336-
337-
## Specifying a service URL
338-
339-
You can set the correct API endpoint for your service calling `setEndPoint()`.
340-
341-
For example, if you have the Discovery service in Germany, the endpoint may be `https://gateway-fra.watsonplatform.net/discovery/api`.
359+
## FAQ
342360

343-
You will need to call
361+
### Does this SDK play well with Android?
344362

345-
```java
346-
Discovery service = new Discovery("2017-11-07");
347-
service.sentEndPoint("https://gateway-fra.watsonplatform.net/discovery/api")
348-
```
363+
It does! You should be able to plug this dependency into your Android app without any issue. In addition, we have an Android SDK meant to be used with this library that adds some Android-specific functionality, which you can find [here](https://github.com/watson-developer-cloud/android-sdk).
349364

350-
## 401 unauthorized error
351-
352-
Make sure you are using the service credentials and not your IBM Cloud account/password.
353-
Check the API endpoint, you may need to update the default using `setEndPoint()`.
354-
355-
## Debug
365+
### How does debugging work?
356366

357367
HTTP requests can be logged by adding a `logging.properties` file to your classpath.
358368

@@ -383,63 +393,21 @@ INFO: <-- 200 OK https://gateway.watsonplatform.net/tradeoff-analytics/api/v1/di
383393

384394
**Warning:** The logs generated by this logger when using the level `FINE` or `ALL` has the potential to leak sensitive information such as "Authorization" or "Cookie" headers and the contents of request and response bodies. This data should only be logged in a controlled way or in a non-production environment.
385395

386-
## Build + test
387-
388-
To build and test the project you can use [Gradle][] (version 1.x).
389-
390-
Gradle:
391-
392-
```sh
393-
cd java-sdk
394-
gradle jar # build jar file (build/libs/watson-developer-cloud-6.14.0.jar)
395-
gradle test # run tests
396-
gradle check # performs quality checks on source files and generates reports
397-
gradle testReport # run tests and generate the aggregated test report (build/reports/allTests)
398-
gradle codeCoverageReport # run tests and generate the code coverage report (build/reports/jacoco)
399-
```
400-
401-
## Working with Eclipse and Intellij IDEA
402-
403-
If you want to work on the code in an IDE instead of a text editor you can
404-
easily create project files with gradle:
405-
406-
```sh
407-
gradle idea # Intellij IDEA
408-
gradle eclipse # Eclipse
409-
```
410-
411-
## Open source @ IBM
412-
413-
Find more open source projects on the [IBM Github Page](http://ibm.github.io/)
414-
415-
## License
416-
417-
This library is licensed under Apache 2.0. Full license text is
418-
available in [LICENSE](LICENSE).
419-
420-
## Contributing
421-
422-
See [CONTRIBUTING.md](.github/CONTRIBUTING.md).
396+
### How can I contribute?
423397

424-
## Code of conduct
398+
Great question (and please do)! You can find contributing information [here](.github/CONTRIBUTING.md).
425399

426-
See [CODE_OF_CONDUCT.md](.github/CODE_OF_CONDUCT.md).
400+
### Where can I get more help with using Watson APIs?
427401

428-
### Other
402+
If you have a question about/problem with using the Watson APIs in general, feel free to ask a question on [dW Answers](https://developer.ibm.com/answers/questions/ask/?topics=watson) or trusty [Stack Overflow](http://stackoverflow.com/questions/ask?tags=ibm-watson).
429403

430-
If you are having difficulties using the APIs or you have a question about the IBM
431-
Watson Services, please ask a question on
432-
[dW Answers](https://developer.ibm.com/answers/questions/ask/?topics=watson)
433-
or [Stack Overflow](http://stackoverflow.com/questions/ask?tags=ibm-watson).
404+
### Does IBM have any other open source work?
434405

406+
We do :sunglasses: http://ibm.github.io/
435407

436408
[wdc]: https://www.ibm.com/watson/developer/
437409
[ibm_cloud]: https://cloud.ibm.com
438-
[Gradle]: http://www.gradle.org/
439-
[OkHttp]: http://square.github.io/okhttp/
440-
[gson]: https://github.com/google/gson
441410
[apache_maven]: http://maven.apache.org/
442-
[sonatype_snapshots]: https://oss.sonatype.org/content/repositories/snapshots/com/ibm/watson/developer_cloud/
443411
[vcap_services]: https://cloud.ibm.com/docs/services/watson/getting-started-variables.html
444412
[ibm-cloud-onboarding]: http://cloud.ibm.com/registration?target=/developer/watson&cm_sp=WatsonPlatform-WatsonServices-_-OnPageNavLink-IBMWatson_SDKs-_-Java
445413

0 commit comments

Comments
 (0)