Added API voice (#743)

Author: Devota Aabel

samples/build.gradle

@@ -10,6 +10,7 @@ dependencies {
   implementation project(":services-geojson")
   implementation project(":services-matching")
   implementation project(":services-staticmap")
+  implementation project(":services-speech")
 }
 
 buildConfig {

samples/src/main/java/com/mapbox/samples/BasicSpeech.java

@@ -0,0 +1,31 @@
+package com.mapbox.samples;
+
+import com.mapbox.api.speech.v1.MapboxSpeech;
+import com.mapbox.sample.BuildConfig;
+
+import okhttp3.ResponseBody;
+import retrofit2.Call;
+import retrofit2.Callback;
+import retrofit2.Response;
+
+public class BasicSpeech {
+
+    public static void main(String[] args) {
+        MapboxSpeech mapboxSpeech = MapboxSpeech.builder()
+                .accessToken(BuildConfig.MAPBOX_ACCESS_TOKEN)
+                .instruction("turn right")
+                .build();
+
+        mapboxSpeech.enqueueCall(new Callback<ResponseBody>() {
+            @Override
+            public void onResponse(Call<ResponseBody> call, Response<ResponseBody> response) {
+                System.out.println(response.body().contentType());
+            }
+
+            @Override
+            public void onFailure(Call<ResponseBody> call, Throwable throwable) {
+                System.out.println(throwable);
+            }
+        });
+    }
+}

services-core/src/main/java/com/mapbox/core/MapboxService.java

@@ -24,7 +24,7 @@ public abstract class MapboxService<T, S> {
 
   private final Class<S> serviceType;
   private boolean enableDebug;
-  private OkHttpClient okHttpClient;
+  protected OkHttpClient okHttpClient;
   private okhttp3.Call.Factory callFactory;
   private Retrofit retrofit;
   private Call<T> call;
@@ -209,7 +209,7 @@ public void setCallFactory(okhttp3.Call.Factory callFactory) {
    * @return OkHttpClient
    * @since 1.0.0
    */
-  public synchronized OkHttpClient getOkHttpClient() {
+  protected synchronized OkHttpClient getOkHttpClient() {
     if (okHttpClient == null) {
       if (isEnableDebug()) {
         HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
@@ -221,7 +221,6 @@ public synchronized OkHttpClient getOkHttpClient() {
         okHttpClient = new OkHttpClient();
       }
     }
-
     return okHttpClient;
   }
 }

services-speech/build.gradle

@@ -0,0 +1,18 @@
+apply plugin: 'java-library'
+
+dependencies {
+    api project(":services-core")
+
+    // Annotations
+    compileOnly dependenciesList.supportAnnotation
+
+    // AutoValue
+    compileOnly dependenciesList.autoValue
+
+    // Test Dependencies
+    testImplementation dependenciesList.okhttp3Mockwebserver
+    testImplementation project(path: ':services-core', configuration: 'testOutput')
+}
+
+apply from: "${rootDir}/gradle/checkstyle.gradle"
+apply from: "${rootDir}/gradle/jacoco.gradle"

services-speech/src/main/java/com/mapbox/api/speech/v1/MapboxSpeech.java

@@ -0,0 +1,191 @@
+package com.mapbox.api.speech.v1;
+
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
+
+import com.google.auto.value.AutoValue;
+import com.mapbox.core.MapboxService;
+import com.mapbox.core.constants.Constants;
+import com.mapbox.core.exceptions.ServicesException;
+import com.mapbox.core.utils.TextUtils;
+
+import java.util.logging.Logger;
+
+import okhttp3.Cache;
+import okhttp3.OkHttpClient;
+import okhttp3.ResponseBody;
+import okhttp3.logging.HttpLoggingInterceptor;
+import retrofit2.Call;
+
+/**
+ * The Speech API is a text-to-speech APi with a server-side caching layer in front of AWS Polly.
+ * The only requirements are text to dictate, and a Mapbox access token. For 3-step-ahead
+ * client-side caching, cache directory is required.
+ *
+ * @since 3.0.0
+ */
+@AutoValue
+public abstract class MapboxSpeech extends MapboxService<ResponseBody, SpeechService> {
+  private static final Logger LOGGER = Logger.getLogger(MapboxSpeech.class.getName());
+
+  protected MapboxSpeech() {
+    super(SpeechService.class);
+  }
+
+  @Override
+  protected Call<ResponseBody> initializeCall() {
+    return getService().getCall(
+            instruction(),
+            textType(),
+            language(),
+            outputType(),
+            accessToken());
+  }
+
+  @Nullable
+  abstract String language();
+
+  @Nullable
+  abstract String textType();
+
+  @Nullable
+  abstract String outputType();
+
+  @Nullable
+  abstract Cache cache();
+
+  @NonNull
+  abstract String accessToken();
+
+  @NonNull
+  abstract String instruction();
+
+  @Override
+  protected abstract String baseUrl();
+
+  @Override
+  public synchronized OkHttpClient getOkHttpClient() {
+    if (okHttpClient == null) {
+      OkHttpClient.Builder httpClient = new OkHttpClient.Builder();
+      if (isEnableDebug()) {
+        HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
+        logging.setLevel(HttpLoggingInterceptor.Level.BASIC);
+        httpClient.addInterceptor(logging);
+      }
+      if (cache() != null) {
+        httpClient.cache(cache());
+      }
+
+      okHttpClient = httpClient.build();
+    }
+    return okHttpClient;
+  }
+
+  /**
+   * Creates a builder for a MapboxSpeech object with a default cache size of 10 MB.
+   *
+   * @return a builder to create a MapboxSpeech object
+   * @since 3.0.0
+   */
+  public static Builder builder() {
+    return new AutoValue_MapboxSpeech.Builder()
+            .baseUrl(Constants.BASE_API_URL);
+  }
+
+  /**
+   * This builder is used to create a MapboxSpeech instance, with details about how the API calls
+   * should be made (input/output format, language, etc.). To use caching, specify a cache
+   * directory. Access token and instruction are required, along with cache directory if you choose
+   * to use caching.
+   *
+   * @since 3.0.0
+   */
+  @AutoValue.Builder
+  public abstract static class Builder {
+    /**
+     * Language of which to request the instructions be spoken. Default is "en-us"
+     *
+     * @param language as a string, i.e., "en-us"
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder language(String language);
+
+    /**
+     * Format which the input is specified. If not specified, default is text
+     *
+     * @param textType either text or ssml
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder textType(String textType);
+
+    /**
+     * Output format for spoken instructions. If not specified, default is mp3
+     *
+     * @param outputType either mp3 or json
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder outputType(String outputType);
+
+    /**
+     * Required to call when this is being built. If no access token provided,
+     * {@link ServicesException} will be thrown.
+     *
+     * @param accessToken Mapbox access token, You must have a Mapbox account in order to use
+     *                    the Optimization API
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder accessToken(@NonNull String accessToken);
+
+    /**
+     * Add the instruction text to dictate, either as plain text or ssml.
+     *
+     * @param instruction to dictate
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder instruction(@NonNull String instruction);
+
+    /**
+     * Optionally change the APIs base URL to something other then the default Mapbox one.
+     *
+     * @param baseUrl base url used as end point
+     * @return this builder for chaining options together
+     * @since 2.1.0
+     */
+    public abstract Builder baseUrl(@NonNull String baseUrl);
+
+    /**
+     * Adds an optional cache to set in the OkHttp client.
+     *
+     * @param cache to set for OkHttp
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder cache(Cache cache);
+
+    abstract MapboxSpeech autoBuild();
+
+    /**
+     * This uses the provided parameters set using the {@link Builder} and first checks that all
+     * values are valid, formats the values as strings for easier consumption by the API, and lastly
+     * creates a new {@link MapboxSpeech} object with the values provided.
+     *
+     * @return a new instance of Mapbox Speech
+     * @throws ServicesException when a provided parameter is detected to be incorrect
+     * @since 3.0.0
+     */
+    public MapboxSpeech build() {
+      MapboxSpeech mapboxSpeech = autoBuild();
+
+      if (TextUtils.isEmpty(mapboxSpeech.instruction())) {
+        throw new ServicesException("Non-null, non-empty instruction text is required.");
+      }
+
+      return mapboxSpeech;
+    }
+  }
+}

services-speech/src/main/java/com/mapbox/api/speech/v1/SpeechService.java

@@ -0,0 +1,35 @@
+package com.mapbox.api.speech.v1;
+
+import okhttp3.ResponseBody;
+import retrofit2.Call;
+import retrofit2.http.GET;
+import retrofit2.http.Path;
+import retrofit2.http.Query;
+
+/**
+ * Interface that defines the speech service.
+ *
+ * @since 3.0.0
+ */
+public interface SpeechService {
+
+  /**
+   * Constructs the html call using the information passed in through the
+   * {@link MapboxSpeech.Builder}.
+   *
+   * @param text            text to dictate
+   * @param textType        text type, either "text" or "ssml" (default is "text")
+   * @param language        language locale, default is "en-us"
+   * @param outputFormat    output format, either "mp3" or "json", default is "mp3"
+   * @param accessToken     Mapbox access token
+   * @return the MapboxSpeech response in a Call wrapper
+   * @since 3.0.0
+   */
+  @GET("/voice/v1/speak/{text}")
+  Call<ResponseBody> getCall(
+          @Path("text") String text,
+          @Query("textType") String textType,
+          @Query("language") String language,
+          @Query("outputFormat") String outputFormat,
+          @Query("access_token") String accessToken);
+}

services-speech/src/main/java/com/mapbox/api/speech/v1/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Contains the Mapbox Java Services wrapper for the Speech API.
+ *
+ * @since 3.0.0
+ */
+package com.mapbox.api.speech.v1;