Cleaned up routeOptions class (#693)

Author: Cameron Mace

samples/build.gradle

@@ -1,6 +1,9 @@
 apply plugin: 'java'
 apply plugin: 'de.fuerstenau.buildconfig'
 
+sourceCompatibility = JavaVersion.VERSION_1_8
+targetCompatibility = JavaVersion.VERSION_1_8
+
 dependencies {
   compile project(":services-core")
   compile project(":services-directions")

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

@@ -1,5 +1,6 @@
 package com.mapbox.samples;
 
+import com.mapbox.api.directions.v5.DirectionsCriteria;
 import com.mapbox.api.directions.v5.MapboxDirections;
 import com.mapbox.api.directions.v5.models.DirectionsResponse;
 import com.mapbox.geojson.Point;
@@ -13,16 +14,17 @@
 /**
  * Shows how to make a directions request using some of the parameters offered.
  */
-public class BasicDirections implements Callback<DirectionsResponse> {
+public class BasicDirections {
 
   public static void main(String[] args) throws IOException {
-
-    buildMapboxDirectionsRequest();
-
-
+    simpleMapboxDirectionsRequest();
+    asyncMapboxDirectionsRequest();
   }
 
-  private static void buildMapboxDirectionsRequest() throws IOException {
+  /**
+   * Demonstrates how to make the most basic directions request.
+   */
+  private static void simpleMapboxDirectionsRequest() throws IOException {
 
     MapboxDirections.Builder builder = MapboxDirections.builder();
 
@@ -36,68 +38,39 @@ private static void buildMapboxDirectionsRequest() throws IOException {
 
     // 3. Log information from the response
     System.out.printf("Check that the response is successful %b", response.isSuccessful());
-    System.out.printf("Get the first routes distance from origin to destination: %f",
+    System.out.printf("%nGet the first routes distance from origin to destination: %f",
       response.body().routes().get(0).distance());
-
-
-//
-//
-//
-//
-//
-//    return MapboxDirections.builder()
-//      .origin(Point.fromLngLat(-95.6332, 29.7890))
-//      .destination(Point.fromLngLat(-95.3591, 29.7576))
-//      .bannerInstructions(true)
-//      .voiceInstructions(true)
-//      .annotations(DirectionsCriteria.ANNOTATION_CONGESTION)
-//      .overview(DirectionsCriteria.OVERVIEW_FULL)
-//      .addBearing(null, null)
-//      .radiuses(Double.POSITIVE_INFINITY, Double.POSITIVE_INFINITY)
-//      .steps(true)
-//      .build();
-  }
-
-
-  @Override
-  public void onResponse(Call<DirectionsResponse> call, Response<DirectionsResponse> response) {
-
   }
 
-  @Override
-  public void onFailure(Call<DirectionsResponse> call, Throwable t) {
-
+  /**
+   * Demonstrates how to make an asynchronous directions request.
+   */
+  private static void asyncMapboxDirectionsRequest() {
+
+    // 1. Pass in all the required information to get a route.
+    MapboxDirections request = MapboxDirections.builder()
+      .accessToken(BuildConfig.MAPBOX_ACCESS_TOKEN)
+      .origin(Point.fromLngLat(-95.6332, 29.7890))
+      .destination(Point.fromLngLat(-95.3591, 29.7576))
+      .profile(DirectionsCriteria.PROFILE_CYCLING)
+      .steps(true)
+      .build();
+
+    // 2. Now request the route using a async call
+    request.enqueueCall(new Callback<DirectionsResponse>() {
+      @Override
+      public void onResponse(Call<DirectionsResponse> call, Response<DirectionsResponse> response) {
+        // 3. Log information from the response
+        if (response.isSuccessful()) {
+          System.out.printf("%nGet the street name of the first step along the route: %s",
+            response.body().routes().get(0).legs().get(0).steps().get(0).name());
+        }
+      }
+
+      @Override
+      public void onFailure(Call<DirectionsResponse> call, Throwable throwable) {
+        System.err.println(throwable);
+      }
+    });
   }
-}
-
-
-//
-//
-//
-//  // 1. Build the directions request using the provided builder.
-//  MapboxDirections directions = buildMapboxDirections();
-//
-//// 2. Use either
-//    directions.enqueueCall(new Callback<DirectionsResponse>() {
-//@Override
-//public void onResponse(Call<DirectionsResponse> call, Response<DirectionsResponse> response) {
-//  System.out.println(response.code());
-//  System.out.println(call.request().url());
-//  System.out.println(response.body().routes().get(0).legs().get(0).steps().get(0).maneuver().location().latitude());
-//  System.out.println(response.body().routes().get(0).distance());
-//  System.out.println(response.body().routes().get(0).routeOptions().profile());
-//  System.out.println(response.body().routes().get(0).routeOptions().alternatives());
-//  System.out.println(response.body().routes().get(0).routeOptions().user());
-//  System.out.println(response.body().routes().get(0).legs().get(0).steps().get(0).maneuver().toString());
-//  System.out.println(response.body().routes().get(0).legs().get(0).steps().get(0)
-//  .voiceInstructions().get(0).announcement());
-//  System.out.println(response.body().routes().get(0).legs().get(0).annotation().congestion().size());
-//  System.out.println("Distance: " + response.body().routes().get(0).legs().get(0).steps().get(0).bannerInstructions().get(0).distanceAlongGeometry());
-//  }
-//
-//@Override
-//public void onFailure(Call<DirectionsResponse> call, Throwable throwable) {
-//  System.out.println(call.request().url());
-//  System.out.println(throwable);
-//  }
-//  });
+}

services-directions/src/main/java/com/mapbox/api/directions/v5/MapboxDirections.java

@@ -101,7 +101,7 @@ private Call<DirectionsResponse> getCall() {
       ApiCallHelper.getHeaderUserAgent(clientAppName()),
       user(),
       profile(),
-      coordinates(),
+      formatCoordinates(coordinates()),
       accessToken(),
       alternatives(),
       geometries(),
@@ -196,6 +196,7 @@ private List<DirectionsRoute> generateRouteOptions(Response<DirectionsResponse>
       modifiedRoutes.add(route.toBuilder().routeOptions(
         RouteOptions.builder()
           .profile(profile())
+          .coordinates(coordinates())
           .continueStraight(continueStraight())
           .annotations(annotation())
           .bearings(bearing())
@@ -215,6 +216,17 @@ private List<DirectionsRoute> generateRouteOptions(Response<DirectionsResponse>
     return modifiedRoutes;
   }
 
+  private static String formatCoordinates(List<Point> coordinates) {
+    List<String> coordinatesFormatted = new ArrayList<>();
+    for (Point point : coordinates) {
+      coordinatesFormatted.add(String.format(Locale.US, "%s,%s",
+        TextUtils.formatCoordinate(point.longitude()),
+        TextUtils.formatCoordinate(point.latitude())));
+    }
+
+    return TextUtils.join(";", coordinatesFormatted.toArray());
+  }
+
   /**
    * Wrapper method for Retrofits {@link Call#cancel()} call, important to manually cancel call if
    * the user dismisses the calling activity or no longer needs the returned results.
@@ -244,7 +256,7 @@ public Call<DirectionsResponse> cloneCall() {
   abstract String profile();
 
   @NonNull
-  abstract String coordinates();
+  abstract List<Point> coordinates();
 
   @NonNull
   abstract String baseUrl();
@@ -696,7 +708,7 @@ public Builder radiuses(@FloatRange(from = 0) double... radiuses) {
      */
     public abstract Builder baseUrl(String baseUrl);
 
-    abstract Builder coordinates(@NonNull String coordinates);
+    abstract Builder coordinates(@NonNull List<Point> coordinates);
 
     abstract MapboxDirections autoBuild();
 
@@ -721,7 +733,7 @@ public MapboxDirections build() {
           + " directions API request.");
       }
 
-      coordinates(formatCoordinates(coordinates));
+      coordinates(coordinates);
       bearing(TextUtils.formatBearing(bearings));
       annotation(TextUtils.join(",", annotations));
       radius(TextUtils.formatRadiuses(radiuses));
@@ -734,16 +746,5 @@ public MapboxDirections build() {
       }
       return directions;
     }
-
-    private static String formatCoordinates(List<Point> coordinates) {
-      List<String> coordinatesFormatted = new ArrayList<>();
-      for (Point point : coordinates) {
-        coordinatesFormatted.add(String.format(Locale.US, "%s,%s",
-          TextUtils.formatCoordinate(point.longitude()),
-          TextUtils.formatCoordinate(point.latitude())));
-      }
-
-      return TextUtils.join(";", coordinatesFormatted.toArray());
-    }
   }
 }

services-directions/src/main/java/com/mapbox/api/directions/v5/models/RouteOptions.java

@@ -1,11 +1,16 @@
 package com.mapbox.api.directions.v5.models;
 
+import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 
 import com.google.auto.value.AutoValue;
 import com.google.gson.Gson;
 import com.google.gson.TypeAdapter;
 import com.mapbox.api.directions.v5.DirectionsCriteria;
+import com.mapbox.api.directions.v5.MapboxDirections;
+import com.mapbox.geojson.Point;
+
+import java.util.List;
 
 /**
  * Provides information connected to your request that help when a new directions request is needing
@@ -41,21 +46,34 @@ public static Builder builder() {
    * @return string value representing the user
    * @since 3.0.0
    */
-  @Nullable
+  @NonNull
   public abstract String user();
 
   /**
    * The same profile which was used during the request that resulted in this root directions
-   * response.
+   * response. {@link MapboxDirections#builder()} ensures that a profile is always set even if the
+   * {@link MapboxDirections} requesting object doesn't specifically set a profile.
    *
    * @return string value representing the profile
    * @since 3.0.0
    */
-  @Nullable
+  @NonNull
   public abstract String profile();
 
   /**
-   * The same alternative setting which was used during the request that resulted in this root
+   * The coordinates used for the routes origin, destination, and optionally, waypoints. Note that
+   * these coordinates are different than the direction responses {@link DirectionsWaypoint}s in
+   * that these are the non-snapped coordinates.
+   *
+   * @return a list of {@link Point}s which represent the route origin, destination, and optionally,
+   *   waypoints
+   * @since 3.0.0
+   */
+  @NonNull
+  public abstract List<Point> coordinates();
+
+  /**
+   * The same alternative setting which were used during the request that resulted in this root
    * directions response.
    *
    * @return boolean object representing the setting for alternatives
@@ -143,12 +161,33 @@ public static Builder builder() {
   @Nullable
   public abstract Boolean bannerInstructions();
 
+  /**
+   * Whether or not the units used inside the voice instruction's string are in imperial or metric.
+   *
+   * @return a string matching either imperial or metric
+   * @since 3.0.0
+   */
   @Nullable
   public abstract String voiceUnits();
 
+  /**
+   * A valid Mapbox access token used to making the request.
+   *
+   * @return a string representing the Mapbox access token
+   * @since 3.0.0
+   */
+  @NonNull
   public abstract String accessToken();
 
-  @Nullable
+  /**
+   * A universally unique identifier (UUID) for identifying and executing a similar specific route
+   * in the future. {@link MapboxDirections} always waits for the response object which ensures this
+   * value will never be null.
+   *
+   * @return a string containing the request UUID
+   * @since 3.0.0
+   */
+  @NonNull
   public abstract String requestUuid();
 
   /**
@@ -177,7 +216,7 @@ public abstract static class Builder {
      * @return this builder for chaining options together
      * @since 3.0.0
      */
-    public abstract Builder user(String user);
+    public abstract Builder user(@NonNull String user);
 
     /**
      * The directions profile that was used during the request time and resulted in this responses
@@ -188,7 +227,19 @@ public abstract static class Builder {
      * @return this builder for chaining options together
      * @since 3.0.0
      */
-    public abstract Builder profile(@Nullable @DirectionsCriteria.ProfileCriteria String profile);
+    public abstract Builder profile(@NonNull @DirectionsCriteria.ProfileCriteria String profile);
+
+    /**
+     * The coordinates used for the routes origin, destination, and optionally, waypoints. Note that
+     * these coordinates are different than the direction responses {@link DirectionsWaypoint}s in
+     * that these are the non-snapped coordinates.
+     *
+     * @param coordinates a list of {@link Point}s which represent the route origin, destination,
+     *                    and optionally, waypoints
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder coordinates(@NonNull List<Point> coordinates);
 
     /**
      * Whether the alternatives value was set to true or not.
@@ -197,7 +248,7 @@ public abstract static class Builder {
      * @return this builder for chaining options together
      * @since 3.0.0
      */
-    public abstract Builder alternatives(Boolean alternatives);
+    public abstract Builder alternatives(@Nullable Boolean alternatives);
 
     /**
      * The language for instructions to be in when the response is given.
@@ -265,11 +316,33 @@ public abstract static class Builder {
      */
     public abstract Builder bannerInstructions(Boolean bannerInstructions);
 
+    /**
+     * Whether or not the units used inside the voice instruction's string are in imperial or metric.
+     *
+     * @param voiceUnits string matching either imperial or metric
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
     public abstract Builder voiceUnits(@Nullable String voiceUnits);
 
-    public abstract Builder accessToken(String accessToken);
+    /**
+     * A valid Mapbox access token used to making the request.
+     *
+     * @param accessToken a string containing a valid Mapbox access token
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder accessToken(@NonNull String accessToken);
 
-    public abstract Builder requestUuid(String requestUuid);
+    /**
+     * A universally unique identifier (UUID) for identifying and executing a similar specific route
+     * in the future.
+     *
+     * @param requestUuid a string containing the request UUID
+     * @return this builder for chaining options together
+     * @since 3.0.0
+     */
+    public abstract Builder requestUuid(@NonNull String requestUuid);
 
     /**
      * The same exclusions the user originally made when the request was made.