Merge pull request #930 from watson-developer-cloud/develop

v5.4.0 Release

Author: lpatino10

README.md

@@ -15,7 +15,10 @@ Java client library to use the [Watson APIs][wdc].
     * [Gradle](#gradle)
   * [Usage](#usage)
   * [Running in IBM Cloud](#running-in-ibm-cloud)
-  * [Getting the Service Credentials](#getting-the-service-credentials)
+  * [Authentication](#authentication)
+    * [Username and Password](#username-and-password)
+    * [API Key](#api-key)
+    * [Using IAM](#using-iam)
   * IBM Watson Services
     * [Assistant](assistant)
     * [Discovery](discovery)
@@ -123,17 +126,92 @@ credentials; the library will get them for you by looking at the [`VCAP_SERVICES
 When running in IBM Cloud (or other platforms based on Cloud Foundry), the library will automatically get the credentials from [`VCAP_SERVICES`][vcap_services].
 If you have more than one plan, you can use `CredentialUtils` to get the service credentials for an specific plan.
 
-## Getting the Service Credentials
+## Authentication
 
-You will need the `username` and `password` (`api_key` for Visual Recognition) credentials, and the API endpoint for each service. Service credentials are different from your IBM Cloud account username and password.
+There are three ways to authenticate with IBM Cloud through the SDK: using a `username` and `password`, using an `api_key`, and with IAM.
 
-To get your service credentials, follow these steps:
+Getting the credentials necessary for authentication is the same process for all methods. To get them, follow these steps:
 
 1. Log in to [IBM Cloud](https://console.bluemix.net/catalog?category=watson)
 1. In the IBM Cloud **Catalog**, select the service you want to use.
 1. Click **Create**.
 1. On the left side of the page, click **Service Credentials**, and then **View credentials** to view your service credentials.
-1. Copy `url`, `username` and `password`(`api_key` for AlchemyAPI or Visual Recognition).
+1. Copy the necessary credentials (`url`, `username`, `password`, `api_key`, `apikey`, etc.).
+
+In your code, you can use these values in the service constructor or with a method call after instantiating your service. Here are some examples:
+
+### Username and Password
+
+```java
+// in the constructor
+Discovery service = new Discovery("2017-11-07", "<username>", "<password>");
+```
+
+```java
+// after instantiation
+Discovery service = new Discovery("2017-11-07");
+service.setUsernameAndPassword("<username>", "<password>");
+```
+
+### API Key
+
+_Note: This version of instantiation only works with Visual Recognition, as it's the only service that uses an API key rather than a username and password._
+
+```java
+// in the constructor
+VisualRecognition service = new VisualRecognition("2016-05-20", "<api_key>");
+```
+
+```java
+// after instantiation
+VisualRecognition service = new VisualRecognition("2016-05-20");
+service.setApiKey("<api_key>");
+```
+
+### Using IAM
+
+When authenticating with IAM, you have the option of passing in:
+- the IAM API key and, optionally, the IAM service URL
+- an IAM access token
+
+**Be aware that passing in an access token means that you're assuming responsibility for maintaining that token's lifecycle.** If you instead pass in an IAM API key, the SDK will manage it for you.
+
+```java
+// in the constructor, 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.ng.bluemix.net/identity/token
+  .build();
+Discovery service = new Discovery("2017-11-07", options);
+```
+
+```java
+// after instantiation, letting the SDK manage the IAM token
+Discovery service = new Discovery("2017-11-07");
+IamOptions options = new IamOptions.Builder()
+  .apiKey("<iam_api_key>")
+  .build();
+service.setIamCredentials(options);
+```
+
+```java
+// in the constructor, assuming control of managing IAM token
+IamOptions options = new IamOptions.Builder()
+  .accessToken("<access_token>")
+  .build();
+Discovery service = new Discovery("2017-11-07", options);
+```
+
+```java
+// after instantiation, assuming control of managing IAM token
+Discovery service = new Discovery("2017-11-07");
+IamOptions options = new IamOptions.Builder()
+  .accessToken("<access_token>")
+  .build();
+service.setIamCredentials(options);
+```
+
+If at any time you would like to let the SDK take over managing your IAM token, simply override your stored IAM credentials with an IAM API key by calling the `setIamCredentials()` method again.
 
 ## Android
 

assistant/src/main/java/com/ibm/watson/developer_cloud/assistant/v1/Assistant.java

@@ -81,6 +81,7 @@
 import com.ibm.watson.developer_cloud.http.RequestBuilder;
 import com.ibm.watson.developer_cloud.http.ServiceCall;
 import com.ibm.watson.developer_cloud.service.WatsonService;
+import com.ibm.watson.developer_cloud.service.security.IamOptions;
 import com.ibm.watson.developer_cloud.util.GsonSingleton;
 import com.ibm.watson.developer_cloud.util.ResponseConverterUtils;
 import com.ibm.watson.developer_cloud.util.Validator;
@@ -129,6 +130,20 @@ public Assistant(String versionDate, String username, String password) {
     setUsernameAndPassword(username, password);
   }
 
+  /**
+   * Instantiates a new `Assistant` with IAM. Note that if the access token is specified in the iamOptions,
+   * you accept responsibility for managing the access token yourself. You must set a new access token before this one
+   * expires. Failing to do so will result in authentication errors after this token expires.
+   *
+   * @param versionDate The version date (yyyy-MM-dd) of the REST API to use. Specifying this value will keep your API
+   *          calls from failing when the service introduces breaking changes.
+   * @param iamOptions the options for authenticating through IAM
+   */
+  public Assistant(String versionDate, IamOptions iamOptions) {
+    this(versionDate);
+    setIamCredentials(iamOptions);
+  }
+
   /**
    * Get a response to a user's input. There is no rate limit for this operation.
    *
@@ -278,8 +293,8 @@ public ServiceCall<WorkspaceExport> getWorkspace(GetWorkspaceOptions getWorkspac
   /**
    * List workspaces.
    *
-   * List the workspaces associated with an Assistant service instance. This operation is limited to 500 requests per 30
-   * minutes. For more information, see **Rate limiting**.
+   * List the workspaces associated with a Watson Assistant service instance. This operation is limited to 500 requests
+   * per 30 minutes. For more information, see **Rate limiting**.
    *
    * @param listWorkspacesOptions the {@link ListWorkspacesOptions} containing the options for the call
    * @return a {@link ServiceCall} with a response type of {@link WorkspaceCollection}
@@ -311,8 +326,8 @@ public ServiceCall<WorkspaceCollection> listWorkspaces(ListWorkspacesOptions lis
   /**
    * List workspaces.
    *
-   * List the workspaces associated with an Assistant service instance. This operation is limited to 500 requests per 30
-   * minutes. For more information, see **Rate limiting**.
+   * List the workspaces associated with a Watson Assistant service instance. This operation is limited to 500 requests
+   * per 30 minutes. For more information, see **Rate limiting**.
    *
    * @return a {@link ServiceCall} with a response type of {@link WorkspaceCollection}
    */

assistant/src/main/java/com/ibm/watson/developer_cloud/assistant/v1/model/CreateDialogNode.java

@@ -12,14 +12,14 @@
  */
 package com.ibm.watson.developer_cloud.assistant.v1.model;
 
-import com.google.gson.annotations.SerializedName;
-import com.ibm.watson.developer_cloud.service.model.GenericModel;
-import com.ibm.watson.developer_cloud.util.Validator;
-
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 
+import com.google.gson.annotations.SerializedName;
+import com.ibm.watson.developer_cloud.service.model.GenericModel;
+import com.ibm.watson.developer_cloud.util.Validator;
+
 /**
  * CreateDialogNode.
  */

assistant/src/main/java/com/ibm/watson/developer_cloud/assistant/v1/model/DialogNode.java

@@ -12,13 +12,13 @@
  */
 package com.ibm.watson.developer_cloud.assistant.v1.model;
 
-import com.google.gson.annotations.SerializedName;
-import com.ibm.watson.developer_cloud.service.model.GenericModel;
-
 import java.util.Date;
 import java.util.List;
 import java.util.Map;
 
+import com.google.gson.annotations.SerializedName;
+import com.ibm.watson.developer_cloud.service.model.GenericModel;
+
 /**
  * DialogNode.
  */

assistant/src/main/java/com/ibm/watson/developer_cloud/assistant/v1/model/DialogNodeVisitedDetails.java

@@ -23,6 +23,7 @@ public class DialogNodeVisitedDetails extends GenericModel {
   @SerializedName("dialog_node")
   private String dialogNode;
   private String title;
+  private String conditions;
 
   /**
    * Gets the dialogNode.
@@ -46,6 +47,17 @@ public String getTitle() {
     return title;
   }
 
+  /**
+   * Gets the conditions.
+   *
+   * The conditions that trigger the dialog node.
+   *
+   * @return the conditions
+   */
+  public String getConditions() {
+    return conditions;
+  }
+
   /**
    * Sets the dialogNode.
    *
@@ -63,4 +75,13 @@ public void setDialogNode(final String dialogNode) {
   public void setTitle(final String title) {
     this.title = title;
   }
+
+  /**
+   * Sets the conditions.
+   *
+   * @param conditions the new conditions
+   */
+  public void setConditions(final String conditions) {
+    this.conditions = conditions;
+  }
 }

assistant/src/main/java/com/ibm/watson/developer_cloud/assistant/v1/model/ListAllLogsOptions.java

@@ -167,7 +167,7 @@ public Long pageLimit() {
   /**
    * Gets the cursor.
    *
-   * A token identifying the last object from the previous page of results.
+   * A token identifying the page of results to retrieve.
    *
    * @return the cursor
    */

assistant/src/main/java/com/ibm/watson/developer_cloud/assistant/v1/model/ListCounterexamplesOptions.java

@@ -205,7 +205,7 @@ public String sort() {
   /**
    * Gets the cursor.
    *
-   * A token identifying the last object from the previous page of results.
+   * A token identifying the page of results to retrieve.
    *
    * @return the cursor
    */

assistant/src/main/java/com/ibm/watson/developer_cloud/assistant/v1/model/ListDialogNodesOptions.java

@@ -205,7 +205,7 @@ public String sort() {
   /**
    * Gets the cursor.
    *
-   * A token identifying the last object from the previous page of results.
+   * A token identifying the page of results to retrieve.
    *
    * @return the cursor
    */

assistant/src/main/java/com/ibm/watson/developer_cloud/assistant/v1/model/ListEntitiesOptions.java

@@ -232,7 +232,7 @@ public String sort() {
   /**
    * Gets the cursor.
    *
-   * A token identifying the last object from the previous page of results.
+   * A token identifying the page of results to retrieve.
    *
    * @return the cursor
    */

assistant/src/main/java/com/ibm/watson/developer_cloud/assistant/v1/model/ListExamplesOptions.java

@@ -234,7 +234,7 @@ public String sort() {
   /**
    * Gets the cursor.
    *
-   * A token identifying the last object from the previous page of results.
+   * A token identifying the page of results to retrieve.
    *
    * @return the cursor
    */