expose include-hov/hot parameters and add exclude list option (#1296)

Author: Pablo Guardiola

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

@@ -178,6 +178,21 @@ public final class DirectionsCriteria {
    */
   public static final String EXCLUDE_RESTRICTED = "restricted";
 
+  /**
+   * A road type that requires a minimum of two vehicle occupants.
+   */
+  public static final String INCLUDE_HOV2 = "hov2";
+
+  /**
+   * A road type that requires a minimum of three vehicle occupants.
+   */
+  public static final String INCLUDE_HOV3 = "hov3";
+
+  /**
+   * An hov road that is tolled if your vehicle doesn't meet the minimum occupant requirement.
+   */
+  public static final String INCLUDE_HOT = "hot";
+
   /**
    * Change the units to imperial for voice and visual information. Note that this won't change
    * other results such as raw distance measurements which will always be returned in meters.
@@ -325,6 +340,18 @@ private DirectionsCriteria() {
   public @interface ExcludeCriteria {
   }
 
+  /**
+   * Retention policy for include key.
+   */
+  @Retention(RetentionPolicy.CLASS)
+  @StringDef( {
+    INCLUDE_HOV2,
+    INCLUDE_HOV3,
+    INCLUDE_HOT
+  })
+  public @interface IncludeCriteria {
+  }
+
   /**
    * Retention policy for the various units of measurements.
    *

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

@@ -353,6 +353,72 @@ public List<String> annotationsList() {
   @Nullable
   public abstract String exclude();
 
+  /**
+   * A list of exclude.
+   * Exclude certain road types from routing. The default is to not exclude anything from the
+   * profile selected. The following exclude flags are available for each profile:
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_DRIVING}: One of {@link DirectionsCriteria#EXCLUDE_TOLL},
+   * {@link DirectionsCriteria#EXCLUDE_MOTORWAY}, or {@link DirectionsCriteria#EXCLUDE_FERRY}.
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_DRIVING_TRAFFIC}: One of
+   * {@link DirectionsCriteria#EXCLUDE_TOLL}, {@link DirectionsCriteria#EXCLUDE_MOTORWAY}, or
+   * {@link DirectionsCriteria#EXCLUDE_FERRY}.
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_WALKING}: No excludes supported
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_CYCLING}: {@link DirectionsCriteria#EXCLUDE_FERRY}
+   *
+   * @return a string matching one of the {@link DirectionsCriteria.ExcludeCriteria} exclusions
+   */
+  @Nullable
+  public List<String> excludeList() {
+    return ParseUtils.parseToStrings(exclude(), ",");
+  }
+
+  /**
+   * Include certain road types in routing. By default, none of the road types listed below
+   * are included. The following include flags are available for each profile:
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_DRIVING}: One of {@link DirectionsCriteria#INCLUDE_HOV2},
+   * {@link DirectionsCriteria#INCLUDE_HOV3}, or {@link DirectionsCriteria#INCLUDE_HOT}.
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_DRIVING_TRAFFIC}: One of
+   * {@link DirectionsCriteria#INCLUDE_HOV2}, {@link DirectionsCriteria#INCLUDE_HOV3}, or
+   * {@link DirectionsCriteria#INCLUDE_HOT}.
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_WALKING}: No includes supported
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_CYCLING}: No includes supported
+   *
+   * @return a string matching one of the {@link DirectionsCriteria.IncludeCriteria} inclusions
+   */
+  @Nullable
+  public abstract String include();
+
+  /**
+   * A list of include.
+   * Include certain road types in routing. By default, none of the road types listed below
+   * are included. The following include flags are available for each profile:
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_DRIVING}: One of {@link DirectionsCriteria#INCLUDE_HOV2},
+   * {@link DirectionsCriteria#INCLUDE_HOV3}, or {@link DirectionsCriteria#INCLUDE_HOT}.
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_DRIVING_TRAFFIC}: One of
+   * {@link DirectionsCriteria#INCLUDE_HOV2}, {@link DirectionsCriteria#INCLUDE_HOV3}, or
+   * {@link DirectionsCriteria#INCLUDE_HOT}.
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_WALKING}: No includes supported
+   * <p>
+   * {@link DirectionsCriteria#PROFILE_CYCLING}: No includes supported
+   *
+   * @return a string matching one of the {@link DirectionsCriteria.IncludeCriteria} inclusions
+   */
+  @Nullable
+  public List<String> includeList() {
+    return ParseUtils.parseToStrings(include(), ",");
+  }
+
   /**
    * Whether to return SSML marked-up text for voice guidance along the route (true) or not
    * (false, default if null).
@@ -1055,7 +1121,8 @@ public Builder layersList(@Nullable List<Integer> layers) {
      */
     @NonNull
     public abstract Builder geometries(
-      @NonNull @DirectionsCriteria.GeometriesCriteria String geometries);
+      @NonNull @DirectionsCriteria.GeometriesCriteria String geometries
+    );
 
     /**
      * Displays the requested type of overview geometry. Can be
@@ -1195,6 +1262,84 @@ public Builder annotationsList(@Nullable List<String> annotations) {
     @NonNull
     public abstract Builder exclude(@Nullable @DirectionsCriteria.ExcludeCriteria String exclude);
 
+    /**
+     * A list of exclude. Exclude certain road types from routing.
+     * The default is to not exclude anything from the profile selected.
+     * The following exclude flags are available for each profile:
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_DRIVING}: One of {@link DirectionsCriteria#EXCLUDE_TOLL},
+     * {@link DirectionsCriteria#EXCLUDE_MOTORWAY}, or {@link DirectionsCriteria#EXCLUDE_FERRY}.
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_DRIVING_TRAFFIC}: One of
+     * {@link DirectionsCriteria#EXCLUDE_TOLL}, {@link DirectionsCriteria#EXCLUDE_MOTORWAY}, or
+     * {@link DirectionsCriteria#EXCLUDE_FERRY}.
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_WALKING}: No excludes supported
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_CYCLING}: {@link DirectionsCriteria#EXCLUDE_FERRY}
+     *
+     * @param exclude a list of exclude that were used during the request
+     * @return this builder for chaining options together
+     */
+    @NonNull
+    public Builder excludeList(@Nullable List<String> exclude) {
+      String result = FormatUtils.join(",", exclude);
+      if (result != null) {
+        exclude(result);
+      }
+      return this;
+    }
+
+    /**
+     * Include certain road types in routing. By default, none of the road types listed below
+     * are included. The following include flags are available for each profile:
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_DRIVING}: One of {@link DirectionsCriteria#INCLUDE_HOV2},
+     * {@link DirectionsCriteria#INCLUDE_HOV3}, or {@link DirectionsCriteria#INCLUDE_HOT}.
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_DRIVING_TRAFFIC}: One of
+     * {@link DirectionsCriteria#INCLUDE_HOV2}, {@link DirectionsCriteria#INCLUDE_HOV3}, or
+     * {@link DirectionsCriteria#INCLUDE_HOT}.
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_WALKING}: No includes supported
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_CYCLING}: No includes supported
+     *
+     * @param include a string matching one of the {@link DirectionsCriteria.IncludeCriteria}
+     *                inclusions
+     * @return this builder for chaining options together
+     */
+    @NonNull
+    public abstract Builder include(@Nullable @DirectionsCriteria.IncludeCriteria String include);
+
+    /**
+     * A list of include. Include certain road types in routing.
+     * By default, none of the road types listed below are included.
+     * The following include flags are available for each profile:
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_DRIVING}: One of {@link DirectionsCriteria#INCLUDE_HOV2},
+     * {@link DirectionsCriteria#INCLUDE_HOV3}, or {@link DirectionsCriteria#INCLUDE_HOT}.
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_DRIVING_TRAFFIC}: One of
+     * {@link DirectionsCriteria#INCLUDE_HOV2}, {@link DirectionsCriteria#INCLUDE_HOV3}, or
+     * {@link DirectionsCriteria#INCLUDE_HOT}.
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_WALKING}: No includes supported
+     * <p>
+     * {@link DirectionsCriteria#PROFILE_CYCLING}: No includes supported
+     *
+     * @param include a list of include that were used during the request
+     * @return this builder for chaining options together
+     */
+    @NonNull
+    public Builder includeList(@Nullable List<String> include) {
+      String result = FormatUtils.join(",", include);
+      if (result != null) {
+        include(result);
+      }
+      return this;
+    }
+
     /**
      * A semicolon-separated list indicating from which side of the road
      * to approach a waypoint.

services-directions-models/src/test/java/com/mapbox/api/directions/v5/models/RouteOptionsTest.java

@@ -41,7 +41,7 @@ public void userIsValid_fromJson() {
   public void profileIsValid_fromJson() {
     RouteOptions routeOptions = RouteOptions.fromJson(optionsJson);
 
-    assertEquals(DirectionsCriteria.PROFILE_DRIVING_TRAFFIC, routeOptions.profile());
+    assertEquals(DirectionsCriteria.PROFILE_DRIVING, routeOptions.profile());
   }
 
   @Test
@@ -168,7 +168,14 @@ public void annotationsAreValid_fromJson() {
   public void excludeIsValid_fromJson() {
     RouteOptions routeOptions = RouteOptions.fromJson(optionsJson);
 
-    assertEquals("toll", routeOptions.exclude());
+    assertEquals("toll,ferry", routeOptions.exclude());
+  }
+
+  @Test
+  public void includeIsValid_fromJson() {
+    RouteOptions routeOptions = RouteOptions.fromJson(optionsJson);
+
+    assertEquals("hot,hov2", routeOptions.include());
   }
 
   @Test
@@ -322,14 +329,15 @@ private RouteOptions routeOptions() {
 
     return RouteOptions.builder()
       .baseUrl("https://api.mapbox.com")
-      .profile(DirectionsCriteria.PROFILE_DRIVING_TRAFFIC)
+      .profile(DirectionsCriteria.PROFILE_DRIVING)
       .coordinatesList(coordinates)
       .alternatives(false)
       .annotations("congestion,distance,duration")
       .bearings("0,90;90,0;")
       .layers("-42;;0")
       .continueStraight(false)
-      .exclude(DirectionsCriteria.EXCLUDE_TOLL)
+      .exclude(DirectionsCriteria.EXCLUDE_TOLL + "," + DirectionsCriteria.EXCLUDE_FERRY)
+      .include(DirectionsCriteria.INCLUDE_HOT + "," + DirectionsCriteria.INCLUDE_HOV2)
       .geometries(DirectionsCriteria.GEOMETRY_POLYLINE6)
       .overview(DirectionsCriteria.OVERVIEW_FULL)
       .radiuses(";unlimited;5.1")
@@ -358,7 +366,7 @@ private RouteOptions routeOptions() {
   }
 
   /**
-   * Fills up all the options using list variants. Values need ot be equal to the ones in {@link #optionsJson}.
+   * Fills up all the options using list variants. Values need to be equal to the ones in {@link #optionsJson}.
    */
   private RouteOptions routeOptionsList() {
     List<Point> coordinates = new ArrayList<>();
@@ -368,7 +376,7 @@ private RouteOptions routeOptionsList() {
 
     return RouteOptions.builder()
       .baseUrl("https://api.mapbox.com")
-      .profile(DirectionsCriteria.PROFILE_DRIVING_TRAFFIC)
+      .profile(DirectionsCriteria.PROFILE_DRIVING)
       .coordinatesList(coordinates)
       .alternatives(false)
       .annotationsList(new ArrayList<String>() {{
@@ -387,7 +395,14 @@ private RouteOptions routeOptionsList() {
         add(0);
       }})
       .continueStraight(false)
-      .exclude(DirectionsCriteria.EXCLUDE_TOLL)
+      .excludeList(new ArrayList<String>() {{
+          add(DirectionsCriteria.EXCLUDE_TOLL);
+          add(DirectionsCriteria.EXCLUDE_FERRY);
+      }})
+      .includeList(new ArrayList<String>() {{
+          add(DirectionsCriteria.INCLUDE_HOT);
+          add(DirectionsCriteria.INCLUDE_HOV2);
+      }})
       .geometries(DirectionsCriteria.GEOMETRY_POLYLINE6)
       .overview(DirectionsCriteria.OVERVIEW_FULL)
       .radiusesList(new ArrayList<Double>() {{

services-directions-models/src/test/resources/route_options_v5.json

@@ -1,7 +1,7 @@
 {
   "baseUrl": "https://api.mapbox.com",
   "user": "mapbox",
-  "profile": "driving-traffic",
+  "profile": "driving",
   "coordinates": "-122.4003312,37.7736941;-122.4187529,37.7689715;-122.4255172,37.7775835",
   "alternatives": false,
   "language": "ru",
@@ -14,7 +14,8 @@
   "overview": "full",
   "steps": true,
   "annotations": "congestion,distance,duration",
-  "exclude": "toll",
+  "exclude": "toll,ferry",
+  "include": "hot,hov2",
   "voice_instructions": true,
   "banner_instructions": true,
   "voice_units": "metric",

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

@@ -24,7 +24,7 @@ interface DirectionsService {
    * @param user                    {@link RouteOptions#user()}
    * @param profile                 {@link RouteOptions#profile()}
    * @param coordinates             {@link RouteOptions#coordinatesList()}
-   * @param accessToken             {@link RouteOptions#accessToken()}
+   * @param accessToken             the access token
    * @param alternatives            {@link RouteOptions#alternatives()}
    * @param geometries              {@link RouteOptions#geometries()}
    * @param overview                {@link RouteOptions#overview()}
@@ -40,6 +40,7 @@ interface DirectionsService {
    * @param bannerInstructions      {@link RouteOptions#bannerInstructions()}
    * @param voiceUnits              {@link RouteOptions#voiceUnits()}
    * @param exclude                 {@link RouteOptions#exclude()}
+   * @param include                 {@link RouteOptions#include()}
    * @param approaches              {@link RouteOptions#approaches()}
    * @param waypointIndices         {@link RouteOptions#waypointIndices()}
    * @param waypointNames           {@link RouteOptions#waypointNames()}
@@ -78,6 +79,7 @@ Call<DirectionsResponse> getCall(
     @Query("banner_instructions") Boolean bannerInstructions,
     @Query("voice_units") String voiceUnits,
     @Query("exclude") String exclude,
+    @Query("include") String include,
     @Query("approaches") String approaches,
     @Query("waypoints") String waypointIndices,
     @Query("waypoint_names") String waypointNames,
@@ -101,7 +103,7 @@ Call<DirectionsResponse> getCall(
    * @param user                    {@link RouteOptions#user()}
    * @param profile                 {@link RouteOptions#profile()}
    * @param coordinates             {@link RouteOptions#coordinatesList()}
-   * @param accessToken             {@link RouteOptions#accessToken()}
+   * @param accessToken             the access token
    * @param alternatives            {@link RouteOptions#alternatives()}
    * @param geometries              {@link RouteOptions#geometries()}
    * @param overview                {@link RouteOptions#overview()}
@@ -117,6 +119,7 @@ Call<DirectionsResponse> getCall(
    * @param bannerInstructions      {@link RouteOptions#bannerInstructions()}
    * @param voiceUnits              {@link RouteOptions#voiceUnits()}
    * @param exclude                 {@link RouteOptions#exclude()}
+   * @param include                 {@link RouteOptions#include()}
    * @param approaches              {@link RouteOptions#approaches()}
    * @param waypointIndices         {@link RouteOptions#waypointIndices()}
    * @param waypointNames           {@link RouteOptions#waypointNames()}
@@ -156,6 +159,7 @@ Call<DirectionsResponse> postCall(
     @Field("banner_instructions") Boolean bannerInstructions,
     @Field("voice_units") String voiceUnits,
     @Field("exclude") String exclude,
+    @Field("include") String include,
     @Field("approaches") String approaches,
     @Field("waypoints") String waypointIndices,
     @Field("waypoint_names") String waypointNames,

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

@@ -95,6 +95,7 @@ private Call<DirectionsResponse> get() {
       routeOptions().bannerInstructions(),
       routeOptions().voiceUnits(),
       routeOptions().exclude(),
+      routeOptions().include(),
       routeOptions().approaches(),
       routeOptions().waypointIndices(),
       routeOptions().waypointNames(),
@@ -134,6 +135,7 @@ private Call<DirectionsResponse> post() {
       routeOptions().bannerInstructions(),
       routeOptions().voiceUnits(),
       routeOptions().exclude(),
+      routeOptions().include(),
       routeOptions().approaches(),
       routeOptions().waypointIndices(),
       routeOptions().waypointNames(),

services-directions/src/test/java/com/mapbox/api/directions/v5/MapboxDirectionsTest.java

@@ -179,7 +179,7 @@ public void profile_doesGetFormattedInUrlCorrectly() throws Exception {
       .accessToken("token")
       .routeOptions(routeOptions)
       .build();
-    assertTrue(directions.cloneCall().request().url().toString().contains("/driving-traffic/"));
+    assertTrue(directions.cloneCall().request().url().toString().contains("/driving/"));
   }
 
   @Test
@@ -358,6 +358,16 @@ public void exclude_doesGetFormattedInUrlCorrectly() throws Exception {
     assertTrue(directions.cloneCall().request().url().toString().contains("exclude=toll"));
   }
 
+  @Test
+  public void include_doesGetFormattedInUrlCorrectly() throws Exception {
+    MapboxDirections directions = MapboxDirections.builder()
+            .accessToken("token")
+            .routeOptions(routeOptions)
+            .build();
+
+    assertTrue(directions.cloneCall().request().url().toString().contains("include=hot"));
+  }
+
   @Test
   public void callFactoryNonNull() throws IOException {
     MapboxDirections client = MapboxDirections.builder()