From 3617f08b126526903c11105d8ebbaba81136c45a Mon Sep 17 00:00:00 2001 From: Kevin Kowalski Date: Tue, 5 Oct 2021 10:55:49 -0500 Subject: [PATCH 1/4] docs(readme): update readme to reflect new builder pattern for the authenticators --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/README.md b/README.md index 6865ecbc261..8f596f39257 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,9 @@ 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. +- There are two ways of initializing an authenticator: + 1. Using the builder of the authenticator (builder pattern). + 2. Using the constructor of the authenticator (deprecated, but it is 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 +155,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("") + .build(); +Discovery service = new Discovery("2019-04-30", authenticator); +``` + +Deprecated constructor approach: + ```java // letting the SDK manage the IAM token Authenticator authenticator = new IamAuthenticator(""); @@ -168,6 +183,18 @@ Discovery service = new Discovery("2019-04-30", authenticator); #### Username and password +Builder pattern approach: + +```java +Authenticator authenticator = new BasicAuthenticator.Builder() + .username("") + .password("") + .build(); +Discovery service = new Discovery("2019-04-30", authenticator); +``` + +Deprecated constructor approach: + ```java Authenticator authenticator = new BasicAuthenticator("", ""); Discovery service = new Discovery("2019-04-30", authenticator); @@ -190,6 +217,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("") + .username("") + .password("") + .disableSSLVerification(true) + .headers(null) + .build(); +Discovery service = new Discovery("2019-04-30", authenticator); +service.setServiceUrl(""); +``` + +Deprecated constructor approach: + ```java // letting the SDK manage the token Authenticator authenticator = new CloudPakForDataAuthenticator( From 9110ac09093e3b7231416a879da4e15ff0df8b61 Mon Sep 17 00:00:00 2001 From: Kevin Kowalski Date: Tue, 5 Oct 2021 15:54:44 -0500 Subject: [PATCH 2/4] docs(readme): update to follow style guidelines --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8f596f39257..ea52ec9b095 100644 --- a/README.md +++ b/README.md @@ -89,9 +89,9 @@ 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. -- There are two ways of initializing an authenticator: - 1. Using the builder of the authenticator (builder pattern). - 2. Using the constructor of the authenticator (deprecated, but it is still available). +- 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). From 08d6f2e1cd7e1440470ff7bfbb296ab99ea06ed0 Mon Sep 17 00:00:00 2001 From: Kevin Kowalski Date: Wed, 6 Oct 2021 11:30:59 -0500 Subject: [PATCH 3/4] docs(readme): add reason for deprecation --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index ea52ec9b095..fc5bba2be6e 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,12 @@ 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 by using the builder pattern. +The main reason is to give us flexibility to add new properties to the authenticator in the future if and when needed, +and to make it easier for users to construct an authenticator instance using the precise set of properties they need to +set for their use-case rather than being forced to use one of the multi-arg constructors (i.e. the one that most closely +matches their requirements). + - 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). From 7a110f88b5df8425748345a86996650782b5ca4a Mon Sep 17 00:00:00 2001 From: Kevin Kowalski Date: Wed, 6 Oct 2021 19:07:01 -0500 Subject: [PATCH 4/4] docs(readme): update readme --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index fc5bba2be6e..b453279934f 100644 --- a/README.md +++ b/README.md @@ -89,11 +89,9 @@ 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 by using the builder pattern. -The main reason is to give us flexibility to add new properties to the authenticator in the future if and when needed, -and to make it easier for users to construct an authenticator instance using the precise set of properties they need to -set for their use-case rather than being forced to use one of the multi-arg constructors (i.e. the one that most closely -matches their requirements). +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).