Directions refresh (#955)

build.gradle

@@ -65,18 +65,19 @@ subprojects {
 }
 
 def TESTABLE_MODULES = ["services",
-                      "services-core",
-                      "services-directions",
-                      "services-geocoding",
-                      "services-geojson",
-                      "services-matching",
-                      "services-matrix",
-                      "services-optimization",
-                      "services-route-tiles",
-                      "services-speech",
-                      "services-staticmap",
-                      "services-tilequery",
-                      "services-turf"]
+                        "services-core",
+                        "services-directions",
+                        "services-geocoding",
+                        "services-geojson",
+                        "services-matching",
+                        "services-matrix",
+                        "services-optimization",
+                        "services-route-tiles",
+                        "services-speech",
+                        "services-staticmap",
+                        "services-tilequery",
+                        "services-turf",
+                        "services-directions-refresh"]
 
 def RELEASE_MODULES = ["services",
                        "services-core",
@@ -85,9 +86,9 @@ def RELEASE_MODULES = ["services",
 
 subprojects { subproject ->
   if (TESTABLE_MODULES.contains(subproject.name)) {
-      subproject.apply plugin: "com.vanniktech.android.junit.jacoco"
-      subproject.apply from: "${rootDir}/gradle/jacoco.gradle"
-      subproject.apply from: "${rootDir}/gradle/checkstyle.gradle"
+    subproject.apply plugin: "com.vanniktech.android.junit.jacoco"
+    subproject.apply from: "${rootDir}/gradle/jacoco.gradle"
+    subproject.apply from: "${rootDir}/gradle/checkstyle.gradle"
   }
 
   if (RELEASE_MODULES.contains(subproject.name)) {

samples/build.gradle

@@ -24,6 +24,7 @@ dependencies {
     implementation project(":services-staticmap")
     implementation project(":services-speech")
     implementation project(":services-tilequery")
+    implementation project(":services-directions-refresh")
 }
 
 buildConfig {

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

@@ -0,0 +1,65 @@
+package com.mapbox.samples;
+
+import com.mapbox.api.directions.v5.MapboxDirections;
+import com.mapbox.api.directions.v5.models.DirectionsResponse;
+import com.mapbox.api.directionsrefresh.v1.MapboxDirectionsRefresh;
+import com.mapbox.api.directionsrefresh.v1.models.DirectionsRefreshResponse;
+import com.mapbox.geojson.Point;
+import com.mapbox.sample.BuildConfig;
+
+import java.io.IOException;
+
+import retrofit2.Call;
+import retrofit2.Callback;
+import retrofit2.Response;
+
+import static com.mapbox.api.directions.v5.DirectionsCriteria.ANNOTATION_CONGESTION;
+import static com.mapbox.api.directions.v5.DirectionsCriteria.OVERVIEW_FULL;
+import static com.mapbox.api.directions.v5.DirectionsCriteria.PROFILE_DRIVING_TRAFFIC;
+
+public class BasicDirectionsRefresh {
+  public static void main(String[] args) throws IOException {
+    String requestId = simpleMapboxDirectionsRequest();
+    simpleMapboxDirectionsRefreshRequest(requestId);
+  }
+
+  private static String simpleMapboxDirectionsRequest() throws IOException {
+    MapboxDirections directions = MapboxDirections.builder()
+      .accessToken(BuildConfig.MAPBOX_ACCESS_TOKEN)
+      .enableRefresh(true)
+      .origin(Point.fromLngLat(-95.6332, 29.7890))
+      .destination(Point.fromLngLat(-95.3591, 29.7576))
+      .overview(OVERVIEW_FULL)
+      .profile(PROFILE_DRIVING_TRAFFIC)
+      .annotations(ANNOTATION_CONGESTION).build();
+
+    Response<DirectionsResponse> response = directions.executeCall();
+    System.out.println("Directions response: " + response);
+    String requestId = response.body().routes().get(0).routeOptions().requestUuid();
+
+    return requestId;
+  }
+
+  private static void simpleMapboxDirectionsRefreshRequest(String requestId) {
+    MapboxDirectionsRefresh refresh =
+      MapboxDirectionsRefresh.builder()
+        .accessToken(BuildConfig.MAPBOX_ACCESS_TOKEN)
+        .requestId(requestId)
+        .routeIndex(0)
+        .legIndex(0)
+        .build();
+
+    refresh.enqueueCall(new Callback<DirectionsRefreshResponse>() {
+      @Override
+      public void onResponse(Call<DirectionsRefreshResponse> call, Response<DirectionsRefreshResponse> response) {
+        System.out.println("Refresh response: " + response);
+      }
+
+      @Override
+      public void onFailure(Call<DirectionsRefreshResponse> call, Throwable throwable) {
+        System.out.println("" + call.request().url());
+        System.out.printf("Failure: " + throwable);
+      }
+    });
+  }
+}

services-directions-refresh/.gitignore

@@ -0,0 +1 @@
+/build

services-directions-refresh/build.gradle

@@ -0,0 +1,19 @@
+apply plugin: 'java-library'
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    api project(":services-core")
+
+    // Annotations
+    compileOnly dependenciesList.supportAnnotation
+
+    // AutoValue
+    compileOnly dependenciesList.autoValue
+    compileOnly dependenciesList.autoValueGson
+    implementation project(":services")
+
+    // Test Dependencies
+    testImplementation dependenciesList.okhttp3Mockwebserver
+    testImplementation project(path: ':services-core', configuration: 'testOutput')
+}
+

services-directions-refresh/src/main/java/com/mapbox/api/directionsrefresh/v1/DirectionsRefreshService.java

@@ -0,0 +1,39 @@
+package com.mapbox.api.directionsrefresh.v1;
+
+import com.mapbox.api.directionsrefresh.v1.models.DirectionsRefreshResponse;
+
+import retrofit2.Call;
+import retrofit2.http.GET;
+import retrofit2.http.Header;
+import retrofit2.http.Path;
+import retrofit2.http.Query;
+
+/**
+ * Interface that defines the directions refresh service. This corresponds to v1 of the
+ * directions API, specifically driving directions.
+ *
+ * @since 4.4.0
+ */
+public interface DirectionsRefreshService {
+
+  /**
+   * Constructs the html call using the information passed in through the
+   * {@link MapboxDirectionsRefresh.Builder}.
+   *
+   * @param userAgent   the user agent
+   * @param requestId   a uuid specifying the request containing the route being refreshed
+   * @param routeIndex  the index of the specified route
+   * @param legIndex    the index of the leg to start the refresh response (inclusive)
+   * @param accessToken Mapbox access token
+   * @return the {@link DirectionsRefreshResponse} in a Call wrapper
+   * @since 4.4.0
+   */
+  @GET("directions-refresh/v1/mapbox/driving-traffic/{request_id}/{route_index}/{leg_index}")
+  Call<DirectionsRefreshResponse> getCall(
+    @Header("User-Agent") String userAgent,
+    @Path("request_id") String requestId,
+    @Path("route_index") int routeIndex,
+    @Path("leg_index") int legIndex,
+    @Query("access_token") String accessToken
+  );
+}

services-directions-refresh/src/main/java/com/mapbox/api/directionsrefresh/v1/MapboxDirectionsRefresh.java

@@ -0,0 +1,165 @@
+package com.mapbox.api.directionsrefresh.v1;
+
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
+
+import com.google.auto.value.AutoValue;
+import com.google.gson.GsonBuilder;
+import com.mapbox.api.directions.v5.DirectionsAdapterFactory;
+import com.mapbox.api.directionsrefresh.v1.models.DirectionsRefreshAdapterFactory;
+import com.mapbox.api.directionsrefresh.v1.models.DirectionsRefreshResponse;
+import com.mapbox.core.MapboxService;
+import com.mapbox.core.constants.Constants;
+import com.mapbox.core.utils.ApiCallHelper;
+
+import retrofit2.Call;
+
+/**
+ * The directions refresh API allows a route to be refreshed via it's annotations. The
+ * refreshEnabled parameter would have had to have been specified as true in the original
+ * directions request for a refresh to be possible.
+ *
+ * @since 4.4.0
+ */
+@AutoValue
+public abstract class MapboxDirectionsRefresh extends MapboxService<DirectionsRefreshResponse,
+  DirectionsRefreshService> {
+
+  private static final int ZERO = 0;
+
+  protected MapboxDirectionsRefresh() {
+    super(DirectionsRefreshService.class);
+  }
+
+  @Override
+  protected Call<DirectionsRefreshResponse> initializeCall() {
+    return getService().getCall(
+      ApiCallHelper.getHeaderUserAgent(clientAppName()),
+      requestId(),
+      routeIndex(),
+      legIndex(),
+      accessToken()
+    );
+  }
+
+  abstract String requestId();
+
+  abstract int routeIndex();
+
+  abstract int legIndex();
+
+  abstract String accessToken();
+
+  @Nullable
+  abstract String clientAppName();
+
+  @NonNull
+  @Override
+  protected abstract String baseUrl();
+
+  @Override
+  protected GsonBuilder getGsonBuilder() {
+    return super.getGsonBuilder()
+      .registerTypeAdapterFactory(DirectionsRefreshAdapterFactory.create())
+      .registerTypeAdapterFactory(DirectionsAdapterFactory.create());
+  }
+
+  /**
+   * Convert the current {@link MapboxDirectionsRefresh} to its builder holding the currently
+   * assigned values. This allows you to modify a single property and then rebuild the object
+   * resulting in an updated and modified {@link MapboxDirectionsRefresh}.
+   *
+   * @return a {@link MapboxDirectionsRefresh.Builder} with the same values
+   * @since 4.4.0
+   */
+  public abstract Builder toBuilder();
+
+  /**
+   * Build a new {@link MapboxDirectionsRefresh} builder with default initial values.
+   *
+   * @return a {@link Builder} for creating a default {@link MapboxDirectionsRefresh}
+   * @since 4.4.0
+   */
+  public static Builder builder() {
+    return new AutoValue_MapboxDirectionsRefresh.Builder()
+      .baseUrl(Constants.BASE_API_URL)
+      .routeIndex(ZERO)
+      .legIndex(ZERO);
+  }
+
+  /**
+   * This builder is used to build a new request to the Mapbox Directions Refresh API. A request
+   * requires an access token and a request id.
+   *
+   * @since 4.4.0
+   */
+  @AutoValue.Builder
+  public abstract static class Builder {
+
+    /**
+     * Specified here is the uuid of the initial directions request. The original request must
+     * have specified enableRefresh.
+     *
+     * @param requestId id of the original directions request. This is found in the
+     * {@link com.mapbox.api.directions.v5.models.RouteOptions} object.
+     * @return this builder
+     * @since 4.4.0
+     */
+    public abstract Builder requestId(String requestId);
+
+    /**
+     * Index of original route in response.
+     *
+     * @param routeIndex index of route in response
+     * @return this builder
+     * @since 4.4.0
+     */
+    public abstract Builder routeIndex(@NonNull int routeIndex);
+
+    /**
+     * Index of leg of which to start. The response will include the annotations of the specified
+     * leg through the end of the list of legs.
+     *
+     * @param legIndex index of leg
+     * @return this builder
+     * @since 4.4.0
+     */
+    public abstract Builder legIndex(@NonNull int legIndex);
+
+    /**
+     * Required to call when this is being built. If no access token provided,
+     * {@link com.mapbox.core.exceptions.ServicesException} will be thrown.
+     *
+     * @param accessToken Mapbox access token
+     * @since 4.4.0
+     */
+    public abstract Builder accessToken(@NonNull String accessToken);
+
+    /**
+     * Base package name or other simple string identifier. Used inside the calls user agent header.
+     *
+     * @param clientAppName base package name or other simple string identifier
+     * @return this builder for chaining options together
+     * @since 4.4.0
+     */
+    public abstract Builder clientAppName(@NonNull String clientAppName);
+
+    /**
+     * Optionally change the APIs base URL to something other then the default Mapbox one.
+     *
+     * @param baseUrl base url used as endpoint
+     * @return this builder
+     * @since 4.4.0
+     */
+    public abstract Builder baseUrl(String baseUrl);
+
+    /**
+     * Returns an instance of {@link MapboxDirectionsRefresh} for interacting with the endpoint
+     * with the specified values.
+     *
+     * @return instance of {@link MapboxDirectionsRefresh} with specified attributes
+     * @since 4.4.0
+     */
+    public abstract MapboxDirectionsRefresh build();
+  }
+}

services-directions-refresh/src/main/java/com/mapbox/api/directionsrefresh/v1/models/DirectionsRefreshAdapterFactory.java

@@ -0,0 +1,24 @@
+package com.mapbox.api.directionsrefresh.v1.models;
+
+import com.google.gson.TypeAdapterFactory;
+import com.ryanharter.auto.value.gson.GsonTypeAdapterFactory;
+
+/**
+ * Required so that AutoValue can generate specific type adapters when needed inside the
+ * directions refresh package.
+ *
+ * @since 4.4.0
+ */
+@GsonTypeAdapterFactory
+public abstract class DirectionsRefreshAdapterFactory implements TypeAdapterFactory {
+
+  /**
+   * Creates a TypeAdapter that AutoValue uses to generate specific type adapters.
+   *
+   * @return a {@link TypeAdapterFactory} to deserialize {@link DirectionsRefreshResponse}
+   * @since 4.4.0
+   */
+  public static TypeAdapterFactory create() {
+    return new AutoValueGson_DirectionsRefreshAdapterFactory();
+  }
+}