[speech-to-text] Added web socket example and code review for web

sockets

Author: germanattanasio

examples/java/com/ibm/watson/developer_cloud/speech_to_text/v1/SpeechToTextExample.java

@@ -1,11 +1,11 @@
 /**
  * Copyright 2015 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
@@ -15,7 +15,6 @@
 
 import java.io.File;
 
-import com.ibm.watson.developer_cloud.http.HttpMediaType;
 import com.ibm.watson.developer_cloud.speech_to_text.v1.model.SpeechResults;
 
 
@@ -30,7 +29,7 @@ public static void main(String[] args) {
     service.setUsernameAndPassword("<username>", "<password>");
 
     File audio = new File("src/test/resources/speech_to_text/sample1.wav");
-    SpeechResults transcript = service.recognize(audio, HttpMediaType.AUDIO_WAV);
+    SpeechResults transcript = service.recognize(audio);
 
     System.out.println(transcript);
   }

src/main/java/com/ibm/watson/developer_cloud/service/ConflictException.java

@@ -0,0 +1,39 @@
+/**
+ * Copyright 2015 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.service;
+
+import com.ibm.watson.developer_cloud.http.HttpStatus;
+import com.squareup.okhttp.Response;
+
+/**
+ * 409 Conflict (HTTP/1.1 - RFC 2616)
+ */
+public class ConflictException extends ServiceResponseException {
+
+  /**
+   * The Constant serialVersionUID.
+   */
+  private static final long serialVersionUID = 1L;
+
+  /**
+   * Instantiates a new Forbidden Exception.
+   * 
+   * @param message the error message
+   * @param response the HTTP response
+   */
+  public ConflictException(String message, Response response) {
+    super(HttpStatus.CONFLICT, message, response);
+  }
+
+}

src/main/java/com/ibm/watson/developer_cloud/service/WatsonService.java

@@ -26,12 +26,14 @@
 import com.google.gson.JsonSyntaxException;
 import com.ibm.watson.developer_cloud.http.HttpHeaders;
 import com.ibm.watson.developer_cloud.http.HttpStatus;
+import com.ibm.watson.developer_cloud.http.RequestBuilder;
 import com.ibm.watson.developer_cloud.service.model.GenericModel;
 import com.ibm.watson.developer_cloud.util.BluemixUtils;
 import com.ibm.watson.developer_cloud.util.RequestUtil;
 import com.ibm.watson.developer_cloud.util.ResponseUtil;
 import com.squareup.okhttp.Credentials;
 import com.squareup.okhttp.Headers;
+import com.squareup.okhttp.HttpUrl;
 import com.squareup.okhttp.OkHttpClient;
 import com.squareup.okhttp.Request;
 import com.squareup.okhttp.Request.Builder;
@@ -69,9 +71,9 @@ public WatsonService(String name) {
 
 
   /**
-   * Configure HTTP client.
+   * Configures the HTTP client.
    * 
-   * @return the okhttp client
+   * @return the HTTP client
    */
   protected OkHttpClient configureHttpClient() {
     final OkHttpClient client = new OkHttpClient();
@@ -147,6 +149,8 @@ protected Response execute(Request request) {
       case HttpStatus.NOT_ACCEPTABLE: // HTTP 406
         throw new ForbiddenException(error != null ? error
             : "Forbidden: Service refuse the request", response);
+      case HttpStatus.CONFLICT: // HTTP 409
+        throw new ConflictException(error != null ? error : "", response);
       case HttpStatus.REQUEST_TOO_LONG: // HTTP 413
         throw new RequestTooLargeException(error != null ? error
             : "Request too large: The request entity is larger than the server is able to process",
@@ -216,6 +220,20 @@ public String getEndPoint() {
     return endPoint;
   }
 
+  /**
+   * Gets an authorization token that can be use to authorize API calls.
+   * 
+   * 
+   * @return the token
+   */
+  public String getToken() {
+    HttpUrl url =
+        HttpUrl.parse(getEndPoint()).newBuilder().setPathSegment(0, "authorization").build();
+    Request request = RequestBuilder.get(url + "/v1/token").withQuery("url", getEndPoint()).build();
+    Response response = execute(request);
+    return ResponseUtil.getJsonObject(response).get("token").getAsString();
+  }
+
   /**
    * Gets the error message from a JSON response
    * 

src/main/java/com/ibm/watson/developer_cloud/speech_to_text/v1/RecognizeOptions.java

@@ -13,26 +13,27 @@
  */
 package com.ibm.watson.developer_cloud.speech_to_text.v1;
 
-import java.util.List;
+import org.apache.commons.lang3.Validate;
 
 import com.google.gson.annotations.SerializedName;
 import com.ibm.watson.developer_cloud.speech_to_text.v1.model.SpeechSession;
+import com.squareup.okhttp.MediaType;
 
 
 /**
- * Recognize Options when using the
- * {@link SpeechToText#recognize(java.io.File, String, RecognizeOptions)} method.
+ * Parameters to be use during a recognize call in the {@link SpeechToText} service.
  */
 public class RecognizeOptions {
 
+
   @SerializedName("content-type")
   private String contentType;
   private Boolean continuous;
   private Integer inactivityTimeout;
 
   @SerializedName("interim_results")
   private Boolean interimResults;
-  private List<String> keywords;
+  private String[] keywords;
 
   @SerializedName("keywords_threshold")
   private Double keywordsThreshold;
@@ -100,7 +101,7 @@ public Boolean getInterimResults() {
    * 
    * @return the keywords
    */
-  public List<String> getKeywords() {
+  public String[] getKeywords() {
     return keywords;
   }
 
@@ -180,7 +181,7 @@ public RecognizeOptions inactivityTimeout(Integer inactivityTimeout) {
 
   /**
    * If true, the service sends interim results for the transcription. Otherwise, the recognition
-   * ends after first "end of speech" is detected. The default is false..
+   * ends after first "end of speech" is detected. The default is false.
    * 
    * @param interimResults the interim results
    * @return the recognize options
@@ -198,7 +199,7 @@ public RecognizeOptions interimResults(Boolean interimResults) {
    * @param keywords the keywords
    * @return the recognize options
    */
-  public RecognizeOptions keywords(List<String> keywords) {
+  public RecognizeOptions keywords(String[] keywords) {
     this.keywords = keywords;
     return this;
   }
@@ -293,12 +294,20 @@ public RecognizeOptions wordAlternativesThreshold(Double wordAlternativesThresho
   }
 
   /**
-   * Content type.
+   * The format of the audio data specified as one of the following values: <br>
+   * <ul>
+   * <li><code>audio/flac</code> for Free Lossless Audio Codec (FLAC)</li>
+   * <li><code>audio/l16</code> for Linear 16-bit Pulse-Code Modulation (PCM)</li>
+   * <li><code>audio/wav</code> for Waveform Audio File Format (WAV)</li>
+   * <li><code>audio/ogg;codecs=opus</code> for Ogg format files that use the opus codec</li>
+   * </ul>
    * 
    * @param contentType the content type
    * @return the recognize options
    */
   public RecognizeOptions contentType(String contentType) {
+    Validate.isTrue(MediaType.parse(contentType) != null,
+        "contentType is not a valid mime audio format. Valid formats start with 'audio/'");
     this.contentType = contentType;
     return this;
   }