Add support of layer to RouteOptions (#1279)

Author: Siarhei Fiedartsou

config/checkstyle/checkstyle.xml

@@ -85,7 +85,7 @@
     at least two characters long.
     -->
     <module name="MemberName">
-      <property name="format" value="^[a-z][a-z0-9][a-zA-Z0-9]*$"/>
+      <property name="format" value="^[a-z][a-z0-9]*[a-zA-Z0-9]*$"/>
       <property name="applyToPublic" value="false"/>
       <message key="name.invalidPattern"
                value="Member name ''{0}'' must start off lowercase and be at least two characters long."/>
@@ -96,7 +96,7 @@
     lower case letter.
     -->
     <module name="MethodName">
-      <property name="format" value="^[a-z][a-z0-9][a-zA-Z0-9_]*$"/>
+      <property name="format" value="^[a-z][a-z0-9]*[a-zA-Z0-9_]*$"/>
       <message key="name.invalidPattern"
                value="Method name ''{0}'' must be at least two characters long."/>
     </module>
@@ -123,7 +123,7 @@
 
     <!-- Require parameter names to be at least two characters long -->
     <module name="ParameterName">
-      <property name="format" value="^[a-z][a-z0-9][a-zA-Z0-9]*$"/>
+      <property name="format" value="^[a-z][a-z0-9]*[a-zA-Z0-9]*$"/>
       <message key="name.invalidPattern"
                value="Parameter name ''{0}'' must be at least two characters long."/>
     </module>
@@ -134,7 +134,7 @@
     -->
     <module name="LocalVariableName">
       <property name="tokens" value="VARIABLE_DEF"/>
-      <property name="format" value="^[a-z][a-z0-9][a-zA-Z0-9]*$"/>
+      <property name="format" value="^[a-z][a-z0-9]*[a-zA-Z0-9]*$"/>
       <property name="allowOneCharVarInForLoop" value="true"/>
       <message key="name.invalidPattern"
                value="Local variable name ''{0}'' must be at least two characters long."/>
@@ -173,7 +173,7 @@
     the format property.
     -->
     <module name="CatchParameterName">
-      <property name="format" value="^[a-z][a-z0-9][a-zA-Z0-9]*$"/>
+      <property name="format" value="^[a-z][a-z0-9]*[a-zA-Z0-9]*$"/>
       <message key="name.invalidPattern"
                value="Catch parameter name ''{0}'' must match pattern ''{1}''."/>
     </module>

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

@@ -198,6 +198,31 @@ public List<Bearing> bearingsList() {
     return ParseUtils.parseBearings(bearings());
   }
 
+  /**
+   * Influences layer of road from where route starts from a waypoint. Useful in ambiguous
+   * cases when there are multiple roads at the same point and only layer allows
+   * to differentiate them.
+   * <p>
+   * If provided, the list of layers must be the same length as the list of coordinates.
+   * @return a string representing the layers with the ; separator. Each value may be negative
+    or absent.
+   */
+  @Nullable
+  public abstract String layers();
+
+  /**
+   * Influences layer of road from where route starts from a waypoint. Useful in ambiguous
+   * cases when there are multiple roads at the same point and only layer allows
+   * to differentiate them.
+   * <p>
+   * If provided, the list of layers must be the same length as the list of coordinates.
+   * @return a List of values representing layers. Each value may be negative or null.
+   */
+  @Nullable
+  public List<Integer> layersList() {
+    return ParseUtils.parseToIntegers(layers());
+  }
+
   /**
    * The allowed direction of travel when departing intermediate waypoints. If true, the route
    * will continue in the same direction of travel. If false, the route may continue in the opposite
@@ -958,6 +983,36 @@ public Builder bearingsList(@Nullable List<Bearing> bearings) {
       return this;
     }
 
+    /**
+     * Influences layer of road from where route starts from a waypoint. Useful in ambiguous
+     * cases when there are multiple roads at the same point and only layer allows
+     * to differentiate them.
+     * <p>
+     * If provided, the list of layers must be the same length as the list of coordinates.
+     * @param layers a string representing the layers with the ; separator.
+     * @return this builder for chaining options together
+     */
+    @NonNull
+    public abstract Builder layers(@Nullable String layers);
+
+    /**
+     * Influences layer of road from where route starts from a waypoint. Useful in ambiguous
+     * cases when there are multiple roads at the same point and only layer allows
+     * to differentiate them.
+     * <p>
+     * If provided, the list of layers must be the same length as the list of coordinates.
+     * @param layers a list of layers. For unknown layer use `null`.
+     * @return this builder for chaining options together
+     */
+    @NonNull
+    public Builder layersList(@Nullable List<Integer> layers) {
+      String result = FormatUtils.formatIntegers(layers);
+      if (result != null) {
+        layers(result);
+      }
+      return this;
+    }
+
     /**
      * The allowed direction of travel when departing intermediate waypoints. If true, the route
      * will continue in the same direction of travel. If false, the route may continue in

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

@@ -169,4 +169,27 @@ public static String formatPointsList(@Nullable List<Point> points) {
     }
     return join(";", coordinatesToJoin);
   }
+
+  /**
+   * Converts list of integers to a string ready for API consumption.
+   *
+   * @param integers a list of integers
+   * @return a formatted string with semicolon separated integers
+   */
+  @Nullable
+  public static String formatIntegers(@Nullable List<Integer> integers) {
+    if (integers == null) {
+      return null;
+    }
+
+    List<String> toJoin = new ArrayList<>();
+    for (Integer integer : integers) {
+      if (integer == null) {
+        toJoin.add(null);
+      } else {
+        toJoin.add(Integer.toString(integer));
+      }
+    }
+    return join(";", toJoin);
+  }
 }

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

@@ -8,11 +8,11 @@
 import com.mapbox.geojson.Point;
 import java.io.IOException;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 import org.junit.Test;
 
 public class RouteOptionsTest extends TestUtils {
-
   /**
    * Always update this file when new option is introduced.
    */
@@ -104,6 +104,31 @@ public void bearingsListIsValid_fromJson() {
     assertNull(routeOptions.bearingsList().get(2));
   }
 
+  @Test
+  public void layersAreValid_fromJson() {
+    RouteOptions routeOptions = RouteOptions.fromJson(optionsJson);
+
+    assertEquals("-42;;0", routeOptions.layers());
+  }
+
+
+  @Test
+  public void layersListIsValid_fromJson() {
+    RouteOptions routeOptions = RouteOptions.fromJson(optionsJson);
+    
+    List<Integer> expected = new ArrayList<Integer>();
+    Collections.addAll(expected, -42, null, 0);
+
+    assertEquals(routeOptions.layersList().size(), expected.size());
+    for (int i = 0; i < expected.size(); ++i) {
+      if (expected.get(i) != null) {
+        assertEquals(expected.get(i), routeOptions.layersList().get(i));
+      } else {
+        assertNull(routeOptions.layersList().get(i));
+      }
+    }
+  }
+
   @Test
   public void continueStraightIsValid_fromJson() {
     RouteOptions routeOptions = RouteOptions.fromJson(optionsJson);
@@ -302,6 +327,7 @@ private RouteOptions routeOptions() {
       .alternatives(false)
       .annotations("congestion,distance,duration")
       .bearings("0,90;90,0;")
+      .layers("-42;;0")
       .continueStraight(false)
       .exclude(DirectionsCriteria.EXCLUDE_TOLL)
       .geometries(DirectionsCriteria.GEOMETRY_POLYLINE6)
@@ -355,6 +381,11 @@ private RouteOptions routeOptionsList() {
         add(Bearing.builder().angle(90.0).degrees(0.0).build());
         add(null);
       }})
+      .layersList(new ArrayList<Integer>() {{
+        add(-42);
+        add(null);
+        add(0);
+      }})
       .continueStraight(false)
       .exclude(DirectionsCriteria.EXCLUDE_TOLL)
       .geometries(DirectionsCriteria.GEOMETRY_POLYLINE6)

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

@@ -7,6 +7,7 @@
   "language": "ru",
   "radiuses": ";unlimited;5.1",
   "bearings": "0,90;90,0;",
+  "layers": "-42;;0",
   "continue_straight": false,
   "roundabout_exits": false,
   "geometries": "polyline6",

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

@@ -31,6 +31,7 @@ interface DirectionsService {
    * @param radiuses                {@link RouteOptions#radiuses()}
    * @param steps                   {@link RouteOptions#steps()}
    * @param bearings                {@link RouteOptions#bearings()}
+   * @param layers                  {@link RouteOptions#layers()}
    * @param continueStraight        {@link RouteOptions#continueStraight()}
    * @param annotations             {@link RouteOptions#annotations()}
    * @param language                {@link RouteOptions#language()}
@@ -68,6 +69,7 @@ Call<DirectionsResponse> getCall(
     @Query("radiuses") String radiuses,
     @Query("steps") Boolean steps,
     @Query("bearings") String bearings,
+    @Query("layers") String layers,
     @Query("continue_straight") Boolean continueStraight,
     @Query("annotations") String annotations,
     @Query("language") String language,
@@ -106,6 +108,7 @@ Call<DirectionsResponse> getCall(
    * @param radiuses                {@link RouteOptions#radiuses()}
    * @param steps                   {@link RouteOptions#steps()}
    * @param bearings                {@link RouteOptions#bearings()}
+   * @param layers                  {@link RouteOptions#layers()}
    * @param continueStraight        {@link RouteOptions#continueStraight()}
    * @param annotations             {@link RouteOptions#annotations()}
    * @param language                {@link RouteOptions#language()}
@@ -144,6 +147,7 @@ Call<DirectionsResponse> postCall(
     @Field("radiuses") String radiuses,
     @Field("steps") Boolean steps,
     @Field("bearings") String bearings,
+    @Field("layers") String layers,
     @Field("continue_straight") Boolean continueStraight,
     @Field("annotations") String annotations,
     @Field("language") String language,

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

@@ -86,6 +86,7 @@ private Call<DirectionsResponse> get() {
       routeOptions().radiuses(),
       routeOptions().steps(),
       routeOptions().bearings(),
+      routeOptions().layers(),
       routeOptions().continueStraight(),
       routeOptions().annotations(),
       routeOptions().language(),
@@ -124,6 +125,7 @@ private Call<DirectionsResponse> post() {
       routeOptions().radiuses(),
       routeOptions().steps(),
       routeOptions().bearings(),
+      routeOptions().layers(),
       routeOptions().continueStraight(),
       routeOptions().annotations(),
       routeOptions().language(),

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

@@ -7,6 +7,7 @@
   "language": "ru",
   "radiuses": ";unlimited;5.1",
   "bearings": "0,90;90,0;",
+  "layers": "-42;;0",
   "continue_straight": false,
   "roundabout_exits": false,
   "geometries": "polyline6",