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

Add changes for v5.3.0 release

Author: germanattanasio

README.md

@@ -14,6 +14,7 @@ Java client library to use the [Watson APIs][wdc].
     * [Maven](#maven)
     * [Gradle](#gradle)
   * [Usage](#usage)
+  * [Running in IBM Cloud](#running-in-ibm-cloud)
   * [Getting the Service Credentials](#getting-the-service-credentials)
   * IBM Watson Services
     * [Assistant](assistant)
@@ -27,11 +28,14 @@ Java client library to use the [Watson APIs][wdc].
     * [Tone Analyzer](tone-analyzer)
     * [Tradeoff Analytics](tradeoff-analytics)
     * [Visual Recognition](visual-recognition)
-  * [Changes for v4.0](#changes-for-v40)
-  * [Using a Proxy](#using-a-proxy)
   * [Android](#android)
-  * [Running in IBM Cloud](#running-in-ibm-cloud)
+  * [Using a Proxy](#using-a-proxy)
   * [Default Headers](#default-headers)
+  * [Sending Request Headers](#sending-request-headers)
+  * [Parsing HTTP Response Info](#parsing-http-response-info)
+  * [Specifying a Service URL](#specifying-a-service-url)
+  * [401 Unauthorized Error](#401-unauthorized-error)
+  * [Changes for v4.0](#changes-for-v40)
   * [Debug](#debug)
   * [Eclipse and Intellij](#working-with-eclipse-and-intellij-idea)
   * [License](#license)
@@ -114,6 +118,11 @@ you will have to create a service in [IBM Cloud][ibm_cloud].
 If you are running your application in IBM Cloud (or other platforms based on Cloud Foundry), you don't need to specify the
 credentials; the library will get them for you by looking at the [`VCAP_SERVICES`][vcap_services] environment variable.
 
+## Running in IBM Cloud
+
+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
 
 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.
@@ -126,12 +135,6 @@ To get your service credentials, follow these steps:
 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).
 
-## Changes for v4.0
-Version 4.0 focuses on the move to programmatically-generated code for many of the services. See the [changelog](https://github.com/watson-developer-cloud/java-sdk/wiki/Changelog) for the details.
-
-## Migration
-This version includes many breaking changes as a result of standardizing behavior across the new generated services. Full details on migration from previous versions can be found [here](https://github.com/watson-developer-cloud/java-sdk/wiki/Migration).
-
 ## Android
 
 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][].
@@ -159,17 +162,53 @@ System.out.println(workspaces);
 
 For more information see: [OkHTTPClient Proxy authentication how to?](https://stackoverflow.com/a/35567936/456564)
 
-## Running in IBM Cloud
-
-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.
-
 ```java
 PersonalityInsights service = new PersonalityInsights("2016-10-19");
 String apiKey = CredentialUtils.getAPIKey(service.getName(), CredentialUtils.PLAN_STANDARD);
 service.setApiKey(apiKey);
 ```
 
+## Sending Request Headers
+
+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:
+
+```java
+WorkspaceCollection workspaces = service.listWorkspaces()
+  .addHeader("Custom-Header", "custom_value")
+  .execute();
+```
+
+## Parsing HTTP Response Info
+
+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.
+
+Here is an example of calling the Watson Assistant `listWorkspaces()` method and parsing its response model as well as the response headers:
+
+```java
+Response<WorkspaceCollection> response = service.listWorkspaces().executeWithDetails();
+
+// getting result equivalent to execute()
+WorkspaceCollection workspaces = response.getResult();
+
+// getting returned HTTP headers
+Headers responseHeaders = response.getHeaders();
+```
+
+Note that when using `enqueueWithDetails()`, you must also implement the new `ServiceCallbackWithDetails` interface. For example:
+
+```java
+service.listWorkspaces().enqueueWithDetails(new ServiceCallbackWithDetails<WorkspaceCollection>() {
+  @Override
+  public void onResponse(Response<WorkspaceCollection> response) {
+    WorkspaceCollection workspaces = response.getResult();
+    Headers responseHeaders = response.getHeaders();
+  }
+
+  @Override
+  public void onFailure(Exception e) { }
+});
+```
+
 ## Default Headers
 
 Default headers can be specified at any time by using the `setDefaultHeaders(Map<String, String> headers)` method.
@@ -187,27 +226,30 @@ service.setDefaultHeaders(headers);
 // All the api calls from now on will send the default headers
 ```
 
-## Specifying a service URL
+## Specifying a Service URL
 
 You can set the correct API Endpoint for your service calling `setEndPoint()`.
 
-For example, if you have the conversation service in Germany, the Endpoint may be `https://gateway-fra.watsonplatform.net/conversation/api`.
+For example, if you have the Discovery service in Germany, the Endpoint may be `https://gateway-fra.watsonplatform.net/discovery/api`.
 
 You will need to call
 
 ```java
-Assistant service = new Assistant("2018-02-16");
-service.sentEndPoint("https://gateway-fra.watsonplatform.net/conversation/api")
+Discovery service = new Discovery("2017-11-07");
+service.sentEndPoint("https://gateway-fra.watsonplatform.net/discovery/api")
 ```
 
-## 401 Unauthorized error
+## 401 Unauthorized Error
 
 Make sure you are using the service credentials and not your IBM Cloud account/password.
 Check the API Endpoint, you may need to update the default using `setEndPoint()`.
 
+## Changes for v4.0
+Version 4.0 focuses on the move to programmatically-generated code for many of the services. See the [changelog](https://github.com/watson-developer-cloud/java-sdk/wiki/Changelog) for the details. This version also includes many breaking changes as a result of standardizing behavior across the new generated services. Full details on migration from previous versions can be found [here](https://github.com/watson-developer-cloud/java-sdk/wiki/Migration).
+
 ## Debug
 
-HTTP requests can be logging by adding a `loggging.properties` file to your classpath.
+HTTP requests can be logged by adding a `logging.properties` file to your classpath.
 
 ```none
 handlers=java.util.logging.ConsoleHandler

core/src/main/java/com/ibm/watson/developer_cloud/http/Headers.java

@@ -0,0 +1,53 @@
+package com.ibm.watson.developer_cloud.http;
+
+import java.util.List;
+import java.util.Set;
+
+/**
+ * Wrapper class for the internal HTTP headers class.
+ */
+public class Headers {
+
+  private okhttp3.Headers headers;
+
+  public Headers(okhttp3.Headers headers) {
+    this.headers = headers;
+  }
+
+  /**
+   * Returns true if other is a Headers object with the same headers, with the same casing, in the same order.
+   *
+   * @param other the other object to compare
+   * @return whether the two objects are equal or not
+   */
+  public boolean equals(Object other) {
+    return this.headers.equals(other);
+  }
+
+  public int hashCode() {
+    return this.headers.hashCode();
+  }
+
+  public String toString() {
+    return this.headers.toString();
+  }
+
+  /**
+   * Returns an immutable, case-insensitive set of header names.
+   *
+   * @return the list of header names
+   */
+  public Set<String> names() {
+    return this.headers.names();
+  }
+
+  /**
+   * Returns an immutable list of the header values for the specified name.
+   *
+   * @param name the name of the specified header
+   * @return the values associated with the name
+   */
+  public List<String> values(String name) {
+    return this.headers.values(name);
+  }
+}

core/src/main/java/com/ibm/watson/developer_cloud/http/Response.java

@@ -0,0 +1,37 @@
+/**
+ * Copyright 2018 IBM Corp. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+package com.ibm.watson.developer_cloud.http;
+
+/**
+ * Class holding the converted service call result along with some HTTP response data.
+ *
+ * @param <T> the generic type
+ */
+public class Response<T> {
+
+  private T result;
+  private Headers headers;
+
+  public Response(T result, okhttp3.Response httpResponse) {
+    this.result = result;
+    this.headers = new Headers(httpResponse.headers());
+  }
+
+  public T getResult() {
+    return this.result;
+  }
+
+  public Headers getHeaders() {
+    return this.headers;
+  }
+}

core/src/main/java/com/ibm/watson/developer_cloud/http/ServiceCall.java

@@ -21,6 +21,15 @@
  */
 public interface ServiceCall<T> {
 
+  /**
+   * Add a header to the request before executing.
+   *
+   * @param name the name of the header
+   * @param value the value of the header
+   * @return the ServiceCall with updated headers
+   */
+  ServiceCall<T> addHeader(String name, String value);
+
   /**
    * Synchronous request.
    *
@@ -29,17 +38,41 @@ public interface ServiceCall<T> {
    */
   T execute() throws RuntimeException;
 
+  /**
+   * Synchronous request with added HTTP information.
+   *
+   * @return a Response object with the generic response model and various HTTP information fields
+   * @throws RuntimeException the exception from the HTTP request
+   */
+  Response<T> executeWithDetails() throws RuntimeException;
+
   /**
    * Asynchronous requests, in this case, you receive a callback when the data has been received.
    *
    * @param callback the callback
    */
   void enqueue(ServiceCallback<? super T> callback);
 
+  /**
+   * Asynchronous requests with added HTTP information. In this case, you receive a callback when the data has been
+   * received.
+   *
+   * @param callback the callback
+   */
+  void enqueueWithDetails(ServiceCallbackWithDetails<T> callback);
+
   /**
    * Reactive requests, in this case, you could take advantage both synchronous and asynchronous.
    *
    * @return a CompletableFuture wrapper for your response
    */
   CompletableFuture<T> rx();
+
+  /**
+   * Reactive requests with added HTTP information. In this case, you could take advantage both synchronous and
+   * asynchronous.
+   *
+   * @return a CompletableFuture wrapper for your response
+   */
+  CompletableFuture<Response<T>> rxWithDetails();
 }

core/src/main/java/com/ibm/watson/developer_cloud/http/ServiceCallbackWithDetails.java

@@ -0,0 +1,35 @@
+/**
+ * Copyright 2018 IBM Corp. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+package com.ibm.watson.developer_cloud.http;
+
+/**
+ * Callback with the response for an Asynchronous request that also provides additional HTTP response information.
+ *
+ * @param <T> the generic type
+ */
+public interface ServiceCallbackWithDetails<T> {
+
+  /**
+   * Called with the response.
+   *
+   * @param response the response
+   */
+  void onResponse(Response<T> response);
+
+  /**
+   * Called if there is an error during the request.
+   *
+   * @param e the exception thrown during the request
+   */
+  void onFailure(Exception e);
+}