Merge pull request #1194 from watson-developer-cloud/update-readme

docs(readme): update readme to reflect new builder pattern for the authenticators

Author: kevinkowa

README.md

@@ -89,6 +89,13 @@ If you have more than one plan, you can use `CredentialUtils` to get the service
 
 Watson services are migrating to token-based Identity and Access Management (IAM) authentication.
 
+As of `v9.2.1`, the preferred approach of initializing an authenticator is the builder pattern. This pattern supports 
+constructing the authenticator with only the properties that you need. Also, if you're authenticating to a Watson service 
+on Cloud Pak for Data that supports IAM, you must use the builder pattern.
+
+- You can initialize the authenticator with either of the following approaches:
+    - In the builder of the authenticator (builder pattern).
+    - In the constructor of the authenticator (deprecated, but still available).
 - 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 Cloud Pak for Data, you'll need to authenticate in a [specific way](#cloud-pak-for-data).
@@ -152,6 +159,18 @@ You supply either an IAM service **API key** or an **access token**:
 
 Supplying the IAM API key:
 
+Builder pattern approach:
+
+```java
+// letting the SDK manage the IAM token
+Authenticator authenticator = new IamAuthenticator.Builder()
+            .apikey("<iam_api_key>")
+            .build();
+Discovery service = new Discovery("2019-04-30", authenticator);
+```
+
+Deprecated constructor approach:
+
 ```java
 // letting the SDK manage the IAM token
 Authenticator authenticator = new IamAuthenticator("<iam_api_key>");
@@ -168,6 +187,18 @@ Discovery service = new Discovery("2019-04-30", authenticator);
 
 #### Username and password
 
+Builder pattern approach:
+
+```java
+Authenticator authenticator = new BasicAuthenticator.Builder()
+            .username("<username>")
+            .password("<password>")
+            .build();
+Discovery service = new Discovery("2019-04-30", authenticator);
+```
+
+Deprecated constructor approach:
+
 ```java
 Authenticator authenticator = new BasicAuthenticator("<username>", "<password>");
 Discovery service = new Discovery("2019-04-30", authenticator);
@@ -190,6 +221,23 @@ service.configureClient(options);
 #### 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.
 
+Builder pattern approach:
+
+```java
+// letting the SDK manage the token
+Authenticator authenticator = new CloudPakForDataAuthenticator.Builder()
+            .url("<CP4D token exchange base URL>")
+            .username("<username>")
+            .password("<password>")
+            .disableSSLVerification(true)
+            .headers(null)
+            .build();
+Discovery service = new Discovery("2019-04-30", authenticator);
+service.setServiceUrl("<service CP4D URL>");
+```
+
+Deprecated constructor approach:
+
 ```java
 // letting the SDK manage the token
 Authenticator authenticator = new CloudPakForDataAuthenticator(