docs: Update all READMEs with auth changes and new core features

Author: lpatino10

README.md

@@ -20,13 +20,14 @@ Java client library to use the [Watson APIs][wdc].
   * [Authentication](#authentication)
     * [IAM](#iam)
     * [Username and password](#username-and-password)
-    * [ICP](#icp)
+    * [Cloud Pak for Data](#cloud-pak-for-data)
   * [Using the SDK](#using-the-sdk)
     * [Parsing responses](#parsing-responses)
     * [Configuring the HTTP client](#configuring-the-http-client)
     * [Making asynchronous API calls](#making-asynchronous-api-calls)
     * [Default headers](#default-headers)
     * [Sending request headers](#sending-request-headers)
+    * [Canceling requests](#canceling-requests)
   * [FAQ](#faq)
   * IBM Watson Services
     * [Assistant](assistant)
@@ -114,7 +115,7 @@ Watson services are migrating to token-based Identity and Access Management (IAM
 
 - With some service instances, you authenticate to the API by using **[IAM](#iam)**.
 - In other instances, you authenticate by providing the **[username and password](#username-and-password)** for the service instance.
-- If you're using a Watson service on ICP, you'll need to authenticate in a [specific way](#icp).
+- If you're using a Watson service on Cloud Pak for Data, you'll need to authenticate in a [specific way](#cloud-pak-for-data).
 
 ### Getting credentials
 
@@ -170,68 +171,56 @@ Some services use token-based Identity and Access Management (IAM) authenticatio
 You supply either an IAM service **API key** or an **access token**:
 
 - Use the API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it if necessary.
-- Use the access token if you want to manage the lifecycle yourself. For details, see [Authenticating with IAM tokens](https://cloud.ibm.com/docs/services/watson/getting-started-iam.html). If you want to switch to API key, override your stored IAM credentials with an IAM API key. Then call the `setIamCredentials()` method again.
+- Use the access token if you want to manage the lifecycle yourself. For details, see [Authenticating with IAM tokens](https://cloud.ibm.com/docs/services/watson/getting-started-iam.html).
 
 
 Supplying the IAM API key:
 
 ```java
 // letting the SDK manage the IAM token
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .url("<iam_url>") // optional - the default value is https://iam.cloud.ibm.com/identity/token
-  .build();
-Discovery service = new Discovery("2017-11-07", options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+Discovery service = new Discovery("2017-11-07", authenticator);
 ```
 
 Supplying the access token:
 
 ```java
 // assuming control of managing IAM token
-IamOptions options = new IamOptions.Builder()
-  .accessToken("<access_token>")
-  .build();
-Discovery service = new Discovery("2017-11-07", options);
+Authenticator authenticator = new BearerTokenAuthenticator("<access_token>");
+Discovery service = new Discovery("2017-11-07", authenticator);
 ```
 
 #### Username and password
 
 ```java
-// in the constructor
-BasicAuthConfig config = new BasicAuthConfig.Builder()
-  .username("<username>")
-  .password("<password")
-  .build();
-Discovery service = new Discovery("2017-11-07", config);
+Authenticator authenticator = new BasicAuthenticator("<username>", "<password>");
+Discovery service = new Discovery("2017-11-07", authenticator);
 ```
 
-#### ICP
+#### Cloud Pak for Data
 Like IAM, you can pass in credentials to let the SDK manage an access token for you or directly supply an access token to do it yourself.
 
 ```java
 // letting the SDK manage the token
-ICP4DConfig config = new ICP4DConfig.Builder()
-  .url("<ICP token exchange base URL>")
-  .username("<username>")
-  .password("<password>")
-  .disableSSLVerification(true)
-  .build();
-Discovery service = new Discovery("2017-11-07", config);
-service.setEndPoint("<service ICP URL>");
+Authenticator authenticator = new CloudPakForDataAuthenticator(
+  "<CP4D token exchange base URL>",
+  "<username>",
+  "<password>",
+  true, // disabling SSL verification
+  null,
+);
+Discovery service = new Discovery("2017-11-07", authenticator);
+service.setEndPoint("<service CP4D URL>");
 ```
 
 ```java
 // assuming control of managing the access token
-ICP4DConfig config = new ICP4DConfig.Builder()
-  .url("<ICP token exchange base URL>")
-  .userManagedAccessToken("<access token>")
-  .disableSSLVerification(true)
-  .build();
-Discovery service = new Discovery("2017-11-07", config);
-service.setEndPoint("<service ICP URL>");
+Authenticator authenticator = new BearerTokenAuthenticator("<access_token>");
+Discovery service = new Discovery("2017-11-07", authenticator);
+service.setEndPoint("<service CP4D URL>");
 ```
 
-Be sure to both disable SSL verification when authenticating and set the endpoint explicitly to the URL given in ICP.
+Be sure to both disable SSL verification when authenticating and set the endpoint explicitly to the URL given in Cloud Pak for Data.
 
 ## Using the SDK
 
@@ -259,8 +248,9 @@ System.out.println("Response header names: " + responseHeaders.names());
 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:
 - Disabling SSL verification (only do this if you really mean to!) ⚠️
 - Using a proxy (more info here: [OkHTTPClient Proxy authentication how to?](https://stackoverflow.com/a/35567936/456564))
+- Setting HTTP logging verbosity
 
-Here's an example of setting both of the above:
+Here's an example of setting the above:
 
 ```java
 Discovery service = new Discovery("2017-11-07");
@@ -269,6 +259,7 @@ Discovery service = new Discovery("2017-11-07");
 HttpConfigOptions options = new HttpConfigOptions.Builder()
   .disableSslVerification(true)
   .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("proxyHost", 8080)))
+  .loggingLevel(HttpConfigOptions.LoggingLevel.BASIC)
   .build();
 
 service.configureClient(options);
@@ -329,7 +320,7 @@ Default headers can be specified at any time by using the `setDefaultHeaders(Map
 The example below sends the `X-Watson-Learning-Opt-Out` header in every request preventing Watson from using the payload to improve the service.
 
 ```java
-PersonalityInsights service = new PersonalityInsights("2016-10-19");
+PersonalityInsights service = new PersonalityInsights("2016-10-19", new NoAuthAuthenticator());
 
 Map<String, String> headers = new HashMap<String, String>();
 headers.put(WatsonHttpHeaders.X_WATSON_LEARNING_OPT_OUT, "true");
@@ -349,6 +340,44 @@ Response<WorkspaceCollection> workspaces = service.listWorkspaces()
   .execute();
 ```
 
+### Canceling requests
+
+It's possible that you may want to cancel a request you make to a service. For example, you may set some timeout threshold and just want to cancel an asynchronous if it doesn't respond in time. You can do that by calling the `cancel()` method on your `ServiceCall` object. For example:
+
+```java
+// time to consider timeout (in ms)
+long timeoutThreshold = 3000;
+
+// storing ServiceCall object we'll use to list our Assistant v1 workspaces
+ServiceCall<WorkspaceCollection> call = service.listWorkspaces();
+
+long startTime = System.currentTimeMillis();
+call.enqueue(new ServiceCallback<WorkspaceCollection>() {
+  @Override
+  public void onResponse(Response<WorkspaceCollection> response) {
+    // store the result somewhere
+    fakeDb.store("my-key", response.getResult());
+  }
+
+  @Override
+  public void onFailure(Exception e) {
+    System.out.println("The request failed :(");
+  }
+});
+
+// keep waiting for the call to complete while we're within the timeout bounds
+while ((fakeDb.retrieve("my-key") == null) && (System.currentTimeMillis() - startTime < timeoutThreshold)) {
+  Thread.sleep(500);
+}
+
+// if we timed out and it's STILL not complete, we'll just cancel the call
+if (fakeDb.retrieve("my-key") == null) {
+    call.cancel();
+}
+```
+
+Doing so will call your `onFailure()` implementation.
+
 ## FAQ
 
 ### Does this SDK play well with Android?

assistant/README.md

@@ -24,11 +24,8 @@ Use the [Assistant][assistant] service to identify intents, entities, and conduc
 // make sure to use the Assistant v1 import!
 import com.ibm.watson.assistant.v1.Assistant;
 
-Assistant service = new Assistant("2018-02-16");
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+Assistant service = new Assistant("2018-02-16", authenticator);
 
 MessageInput input = new MessageInput();
 input.setText("Hi");
@@ -78,11 +75,8 @@ System.out.println(response);
 // make sure to use the Assistant v2 import!
 import com.ibm.watson.assistant.v2.Assistant;
 
-Assistant service = new Assistant("2018-09-20");
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+Assistant service = new Assistant("2018-09-20", authenticator);
 
 MessageInput input = new MessageInput.Builder()
   .text("Hi")

compare-comply/README.md

@@ -19,11 +19,8 @@
 ## Usage
 Use the [Compare and Comply](https://cloud.ibm.com/docs/services/compare-comply/index.html#about) service to enable better and faster document understanding. Below is an example of converting a PDF file into HTML:
 ```java
-CompareComply service = new CompareComply("2018-10-15");
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+CompareComply service = new CompareComply("2018-10-15", authenticator);
 
 ConvertToHtmlOptions convertToHtmlOptions = new ConvertToHtmlOptions.Builder()
   .file("~/path/to/file.pdf")

discovery/README.md

@@ -20,11 +20,8 @@
 The [Discovery][discovery] wraps the environment, collection, configuration, document, and query operations of the Discovery service.
 
 ```java
-Discovery discovery = new Discovery("2017-11-07");
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+Discovery discovery = new Discovery("2017-11-07", authenticator);
 
 //Build an empty query on an existing environment/collection
 String environmentId = "<environmentId>";

language-translator/README.md

@@ -21,11 +21,8 @@ Select a domain, then identify or select the language of text, and then translat
 Example: Translate 'hello' from English to Spanish using the [Language Translator][language_translator] service.
 
 ```java
-LanguageTranslator service = new LanguageTranslator();
-IamOptions iamOptions = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(iamOptions);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+LanguageTranslator service = new LanguageTranslator(authenticator);
 
 TranslateOptions translateOptions = new TranslateOptions.Builder()
   .addText("hello")

natural-language-classifier/README.md

@@ -20,11 +20,8 @@
 Use [Natural Language Classifier](https://cloud.ibm.com/docs/services/natural-language-classifier?topic=natural-language-classifier-natural-language-classifier) service to create a classifier instance by providing a set of representative strings and a set of one or more correct classes for each as training. Then use the trained classifier to classify your new question for best matching answers or to retrieve next actions for your application.
 
 ```java
-NaturalLanguageClassifier service = new NaturalLanguageClassifier();
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+NaturalLanguageClassifier service = new NaturalLanguageClassifier(authenticator);
 
 ClassifyOptions classifyOptions = new ClassifyOptions.Builder()
   .classifierId("<classifier-id>")

natural-language-understanding/README.md

@@ -23,15 +23,12 @@ Language Understanding will give you results for the features you request. The s
 analysis by default, so the results can ignore most advertisements and other unwanted content.
 
 ```java
-NaturalLanguageUnderstanding service = new NaturalLanguageUnderstanding("2017-02-27");
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+NaturalLanguageUnderstanding service = new NaturalLanguageUnderstanding("2017-02-27", authenticator);
 
 EntitiesOptions entities = new EntitiesOptions.Builder()
   .sentiment(true)
-  .limit(1)
+  .limit(1L)
   .build();
 Features features = new Features.Builder()
   .entities(entities)

personality-insights/README.md

@@ -21,11 +21,8 @@ Use linguistic analytics to infer personality and social characteristics, includ
 Example: Analyze text and get a personality profile using the [Personality Insights][personality_insights] service.
 
 ```java
-PersonalityInsights service = new PersonalityInsights("2016-10-19");
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+PersonalityInsights service = new PersonalityInsights("2016-10-19", authenticator);
 
 // Demo content from Moby Dick by Hermann Melville (Chapter 1)
 String text = "Call me Ishmael. Some years ago-never mind how long precisely-having "

speech-to-text/README.md

@@ -20,11 +20,8 @@
 Use the [Speech to Text][speech_to_text] service to recognize the text from a .wav file.
 
 ```java
-SpeechToText service = new SpeechToText();
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+SpeechToText service = new SpeechToText(authenticator);
 
 File audio = new File("src/test/resources/sample1.wav");
 
@@ -42,11 +39,8 @@ System.out.println(transcript);
 Speech to Text supports WebSocket, the url is: `wss://stream.watsonplatform.net/speech-to-text/api/v1/recognize`
 
 ```java
-SpeechToText service = new SpeechToText();
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+SpeechToText service = new SpeechToText(authenticator);
 
 InputStream audio = new FileInputStream("src/test/resources/sample1.wav");
 

text-to-speech/README.md

@@ -20,11 +20,8 @@
 Use the [Text to Speech][text_to_speech] service to get the available voices to synthesize.
 
 ```java
-TextToSpeech service = new TextToSpeech();
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+TextToSpeech service = new TextToSpeech(authenticator);
 
 Voices voices = service.listVoices().execute().getResult();
 System.out.println(voices);
@@ -33,11 +30,8 @@ System.out.println(voices);
 ## Usage with WebSockets
 The Watson Text to Speech service supports the use of WebSockets as an alternative to the `synthesize()` method, which converts text to speech. Here is an example of using the WebSocket version of the method to get an audio file:
 ```java
-TextToSpeech service = new TextToSpeech();
-IamOptions options = new IamOptions.Builder()
-  .apiKey("<iam_api_key>")
-  .build();
-service.setIamCredentials(options);
+Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
+TextToSpeech service = new TextToSpeech(authenticator);
 
 String text = "It's beginning to look a lot like Christmas";
 SynthesizeOptions synthesizeOptions = new SynthesizeOptions.Builder()