Add map matching property getters (#270)

* Add mapmatching property parsers and their tests

* Clean up unused imports and unthrown exception

* Fix Typo

* Fix more typo

* Testing user name

* Update property parser and testing

* Remove coord times from response

* Clean up unused import. validate checkstyle, test-java, test-android

Author: jl-skyline

mapbox/app/src/main/java/com/mapbox/services/android/testapp/utils/MapMatchingActivity.java

@@ -221,10 +221,15 @@ public void onResponse(Call<MapMatchingResponse> call, Response<MapMatchingRespo
           // Check that the map matching API response is "OK".
           if (response.code() == 200) {
             // Convert the map matched response list from position to latlng coordinates.
-            for (int i = 0; i < response.body().getMatchedPoints().length; i++) {
+            Position[] positions = response.body().getMatchedPoints();
+            if (positions == null) {
+              return;
+            }
+
+            for (int i = 0; i < positions.length; i++) {
               mapMatchedPoints.add(new LatLng(
-                response.body().getMatchedPoints()[i].getLatitude(),
-                response.body().getMatchedPoints()[i].getLongitude()));
+                      positions[i].getLatitude(),
+                      positions[i].getLongitude()));
             }
 
             if (mapMatchedRoute != null) {

mapbox/libjava-geojson/src/test/java/com/mapbox/services/commons/geojson/FeatureTest.java

@@ -52,5 +52,4 @@ public void testNonNullProperties() {
     Feature feature = Feature.fromGeometry(line, properties);
     assertTrue(feature.toJson().contains("\"properties\":{\"key\":\"value\"}"));
   }
-
 }

mapbox/libjava-services/src/main/java/com/mapbox/services/api/mapmatching/v4/models/MapMatchingResponse.java

@@ -6,10 +6,12 @@
 import com.mapbox.services.commons.geojson.FeatureCollection;
 import com.mapbox.services.commons.models.Position;
 
+import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Mapbox map matching API response
+ * Mapbox map matching API response and convenience getter methods for optional properties
+ * @see <a href="https://www.mapbox.com/api-documentation/#retrieve-a-match">Map Matching API Documentation</a>
  *
  * @since 1.2.0
  */
@@ -19,6 +21,9 @@ public class MapMatchingResponse extends FeatureCollection {
 
   private String code;
 
+  /** A placeholder for the best matched points for optimizing multiple calls */
+  private Position[] bestMatchedPoints;
+
   public MapMatchingResponse(List<Feature> features) {
     super(features);
   }
@@ -56,7 +61,7 @@ public void setCode(String code) {
    * @since 1.2.0
    */
   public Position[] getMatchedPoints() {
-    return getMatchedPoints(0);
+    return bestMatchedPoints != null ? bestMatchedPoints : (bestMatchedPoints = getMatchedPoints(0));
   }
 
   /**
@@ -65,6 +70,31 @@ public Position[] getMatchedPoints() {
    * create several sub-matches, each as a feature. The higher the number of features, the more
    * likely that the input traces are poorly aligned to the road network.
    *
+   * <p>
+   * Implementation Note:<br>
+   * A caller should consider using returned array as an instance rather than as a reference to the array
+   *
+   * <pre>
+   *   for (int index = 0; index < MapMatchingResponse.getMatchedPoints(bestIndex).length; index++) {
+   *     .. do some work
+   *     double latitude = MapMatchingResponse.getMatchedPoints(bestIndex).getLatitude();
+   *     .. do more work
+   *   }
+   * </pre>
+   * <p>This can be optimized in performance as below</p>
+   * <pre>
+   *   Position[] points = MapMatchingResponse.getMatchedPoints(bestIndex);
+   *   if (points == null) {
+   *     return;
+   *   }
+   *
+   *   for (int index = 0; index < points.length; index++) {
+   *     .. do some work
+   *     double latitude = points[index].getLatitude();
+   *     .. do more work
+   *   }
+   * </pre>
+   *
    * @param submatch Which sub-match you want to get the position for.
    * @return Array of {@link Position} that have been map matched.
    * @since 1.2.0
@@ -79,7 +109,73 @@ public Position[] getMatchedPoints(int submatch) {
         points.get(i).getAsJsonArray().get(0).getAsDouble(),
         points.get(i).getAsJsonArray().get(1).getAsDouble());
     }
+
     return positions;
   }
 
+  /**
+   * Convenience method to get a confidence value from Map Matching Response
+   *
+   * @param submatch A MapMatching sub-match value
+   * @return a confidence value when a property exists and contains non-null value, otherwise null
+   */
+  public Number getConfidence(int submatch) {
+    final String CONFIDENCE = "confidence";
+    if (!getFeatures().get(submatch).hasNonNullValueForProperty(CONFIDENCE)) {
+      return null;
+    }
+
+    return getFeatures().get(submatch).getProperties().get(CONFIDENCE).getAsNumber();
+  }
+
+  /**
+   * Convenience method to get distance property on Map Matching Response
+   *
+   * @param submatch A MapMatching sub-match value
+   * @return total distance in meters when a property exists and contains non-null value, otherwise null
+   */
+  public Number getDistance(int submatch) {
+    final String DISTANCE = "distance";
+    if (!getFeatures().get(submatch).hasNonNullValueForProperty(DISTANCE)) {
+      return null;
+    }
+
+    return getFeatures().get(submatch).getProperties().get(DISTANCE).getAsNumber();
+  }
+
+  /**
+   * Convenience method to get duration property on Map Matching Response
+   *
+   * @param submatch A MapMatching sub-match value
+   * @return travel time in seconds when a property exists and contains non-null value, otherwise null
+   */
+  public Number getDuration(int submatch) {
+    final String DURATION = "duration";
+    if (!getFeatures().get(submatch).hasNonNullValueForProperty(DURATION)) {
+      return null;
+    }
+
+    return getFeatures().get(submatch).getProperties().get(DURATION).getAsNumber();
+  }
+
+  /**
+   * Convenience method to get coordinate times property on Feature
+   *
+   * @param submatch A MapMatching sub-match value
+   * @return Array of indices when a property exists and contains non-null value, otherwise null
+   */
+  public List<Integer> getIndices(int submatch) {
+    final String INDICES = "indices";
+    if (!getFeatures().get(submatch).hasNonNullValueForProperty(INDICES)) {
+      return null;
+    }
+
+    JsonArray rawIndices = getFeatures().get(submatch).getProperty(INDICES).getAsJsonArray();
+    List<Integer> indices = new ArrayList<>();
+    for (int i = 0; i < rawIndices.size(); i ++) {
+      indices.add(rawIndices.get(i).getAsInt());
+    }
+
+    return indices;
+  }
 }

mapbox/libjava-services/src/test/fixtures/mapmatching_v5_polyline.json

@@ -1 +1 @@
-{"code":"Ok","type":"FeatureCollection","features":[{"type":"Feature","geometry":"}}_rXahkccBz@OzEs@{O{Ws@kAaG}JsIoMwIwMuU}]uBgDg[sg@","properties":{"confidence":0.8820996720716853,"distance":291.6,"duration":40.5,"matchedPoints":[[13.418991,52.500625],[13.419147,52.501095],[13.419618,52.501754],[13.42004,52.502333],[13.420492,52.502983]],"indices":[0,1,2,3,4]}}]}
+{"code":"Ok","type":"FeatureCollection","features":[{"type":"Feature","geometry":"}}_rXahkccBz@OzEs@{O{Ws@kAaG}JsIoMwIwMuU}]uBgDg[sg@","properties":{"confidence":0.8820996720716853,"distance":291.6,"duration":40.5,"matchedPoints":[[13.418991,52.500625],[13.419147,52.501095],[13.419618,52.501754],[13.42004,52.502333],[13.420492,52.502983]],"indices":[0,1,2,3,4]}}]}

mapbox/libjava-services/src/test/java/com/mapbox/services/api/mapmatching/v4/MapboxMapMatchingTest.java

@@ -15,7 +15,9 @@
 import java.nio.charset.Charset;
 import java.nio.file.Files;
 import java.nio.file.Paths;
+import java.text.ParseException;
 import java.util.ArrayList;
+import java.util.List;
 
 import okhttp3.HttpUrl;
 import okhttp3.mockwebserver.Dispatcher;
@@ -215,6 +217,38 @@ public void testUserAgent() throws ServicesException, IOException {
     assertTrue(service.executeCall().raw().request().header("User-Agent").contains("APP"));
   }
 
+  @Test
+  public void validConvenientMethodsFetchingMapMatchingProperties()
+          throws ServicesException, IOException, ParseException {
+    MapboxMapMatching client = new MapboxMapMatching.Builder()
+            .setAccessToken(ACCESS_TOKEN)
+            .setProfile(MapMatchingCriteria.PROFILE_DRIVING)
+            .setTrace(trace)
+            .setBaseUrl(mockUrl.toString())
+            .build();
+    Response<MapMatchingResponse> response = client.executeCall();
+    assertEquals(response.code(), 200);
+
+    // Check the response body
+    assertNotNull(response.body());
+    assertEquals(1, response.body().getFeatures().size());
+
+    assertEquals("property confidence", 0.8820996720716853,
+            response.body().getConfidence(0).doubleValue(), 0);
+    assertEquals("property distance", 291.6,
+            response.body().getDistance(0).doubleValue(), 0);
+    assertEquals("property duration", 40.5,
+            response.body().getDuration(0).doubleValue(), 0);
+
+    int[] mockIndices = new int[] {0, 1, 2, 3, 4};
+    List<Integer> indices = response.body().getIndices(0);
+
+    // test indices counts
+    assertEquals("property indices count", 5, indices.size());
+    // sampling indices at 2
+    assertEquals("property indices count", mockIndices[2], indices.get(2).doubleValue(), 0);
+  }
+
   //  @Test
   //  public void testPost() throws ServicesException, IOException {
   //    MapboxMapMatching client = new MapboxMapMatching.Builder()