NAVAND-713: publicly expose unrecognized properties

Author: dzinad

CHANGELOG.md

@@ -3,6 +3,10 @@
 Mapbox welcomes participation and contributions from everyone.
 
 ### main
+- Added `getUnrecognizedJsonProperties()` method to `DirectionsRefreshJsonObject` so that unrecognized properties can be received from refresh response.
+- Added `DirectionsRefreshJsonObject.Builder#unrecognizedJsonProperties`. [#1500](https://github.com/mapbox/mapbox-java/pull/1500)
+- Added `getUnrecognizedJsonProperties()` method to `DirectionsJsonObject` so that a map of unrecognized properties can be received from route response.
+- Added `DirectionsJsonObject.Builder#unrecognizedJsonProperties`. [#1500](https://github.com/mapbox/mapbox-java/pull/1500)
 
 ### v6.8.0 - September 29, 2022
 - Replaced `TurfSimplify#simplify` with `TurfTransformation#simplify`. [#1496](https://github.com/mapbox/mapbox-java/pull/1496)

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

@@ -5,10 +5,11 @@
 import com.google.gson.GsonBuilder;
 import com.google.gson.JsonElement;
 import com.mapbox.api.directions.v5.DirectionsAdapterFactory;
-import com.mapbox.geojson.Point;
-import com.mapbox.geojson.PointAsCoordinatesTypeAdapter;
+import com.mapbox.api.directions.v5.utils.UnrecognizedPropertiesUtils;
 import com.mapbox.auto.value.gson.SerializableJsonElement;
 import com.mapbox.auto.value.gson.UnrecognizedJsonProperties;
+import com.mapbox.geojson.Point;
+import com.mapbox.geojson.PointAsCoordinatesTypeAdapter;
 
 import java.io.Serializable;
 import java.util.Collections;
@@ -89,12 +90,44 @@ public final Set<String> getUnrecognizedPropertiesNames() {
     return result;
   }
 
+  /**
+   * Use this method to get JSON properties that weren't recognized during JSON
+   * serialization by the model. This may be useful to access experimental API properties.
+   * When an experimental API property becomes stable,
+   * it will eventually have static field in a model introduced
+   * and it won't be available via this dynamic method anymore.
+   *
+   * See
+   * <a href="https://docs.mapbox.com/api/navigation/directions/">Directions API documentation</a>
+   * for available experimental fields.
+   *
+   * @return unrecognized JSON properties
+   */
+  @Nullable
+  public final Map<String, JsonElement> getUnrecognizedJsonProperties() {
+    return UnrecognizedPropertiesUtils.fromSerializableProperties(unrecognized());
+  }
+
   @Nullable
   @UnrecognizedJsonProperties
   abstract Map<String, SerializableJsonElement> unrecognized();
 
   abstract static class Builder<T extends Builder> {
     @NonNull
     abstract T unrecognized(@Nullable Map<String, SerializableJsonElement> value);
+
+    /**
+     * Use this method to add parameters which are not present in the model yet but are supported
+     * on the Directions API side in the response.
+     * Use it for experimental parameters.
+     *
+     * @param unrecognizedProperties parameters to add to request
+     */
+    @NonNull
+    public T unrecognizedJsonProperties(@Nullable Map<String, JsonElement> unrecognizedProperties) {
+      return unrecognized(
+        UnrecognizedPropertiesUtils.toSerializableProperties(unrecognizedProperties)
+      );
+    }
   }
 }

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

@@ -0,0 +1,54 @@
+package com.mapbox.api.directions.v5.utils;
+
+import androidx.annotation.Nullable;
+import com.google.gson.JsonElement;
+import com.mapbox.auto.value.gson.SerializableJsonElement;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Provides utility methods to work with unrecognized properties.
+ */
+public final class UnrecognizedPropertiesUtils {
+
+  /**
+   * Converts unrecognized properties in form of Map<String, SerializableJsonElement<
+   *   to unrecognized properties in form of Map<String, JsonElement<.
+   * @param unrecognizedProperties original map
+   * @return converted map
+   */
+  @Nullable
+  public static Map<String, JsonElement> fromSerializableProperties(
+    @Nullable Map<String, SerializableJsonElement> unrecognizedProperties
+  ) {
+    if (unrecognizedProperties != null) {
+      Map<String, JsonElement> result = new HashMap<>();
+      for (String key : unrecognizedProperties.keySet()) {
+        result.put(key, unrecognizedProperties.get(key).getElement());
+      }
+      return result;
+    }
+    return null;
+  }
+
+  /**
+   * Converts unrecognized properties in form of Map&#60;String, JsonElement&#60;.
+   *   to unrecognized properties in form of Map&#60;String, SerializableJsonElement&#60;.
+   * @param unrecognizedProperties original map
+   * @return converted map
+   */
+  @Nullable
+  public static Map<String, SerializableJsonElement> toSerializableProperties(
+    @Nullable Map<String, JsonElement> unrecognizedProperties
+  ) {
+    if (unrecognizedProperties != null) {
+      Map<String, SerializableJsonElement> result = new HashMap<>();
+      for (Map.Entry<String, JsonElement> entry : unrecognizedProperties.entrySet()) {
+        result.put(entry.getKey(), new SerializableJsonElement(entry.getValue()));
+      }
+      return result;
+    }
+    return null;
+  }
+}

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

@@ -10,11 +10,15 @@
 import com.mapbox.geojson.Point;
 
 import java.io.IOException;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
 import java.util.List;
 
 import org.junit.Test;
 
 import java.util.ArrayList;
+import java.util.Map;
 import java.util.Set;
 
 import static com.mapbox.api.directions.v5.utils.MutateJsonUtil.mutateJson;
@@ -34,11 +38,41 @@ public class DirectionsResponseTest extends TestUtils {
 
   @Test
   public void sanity() throws Exception {
+    Metadata metadata = Metadata.builder().infoMap(Collections.singletonMap("aaa", "bbb")).build();
+    List<DirectionsWaypoint> waypoints = Arrays.asList(
+      DirectionsWaypoint
+        .builder()
+        .rawLocation(new double[0])
+        .distance(9.8)
+        .name("aaa")
+        .build()
+    );
+    List<DirectionsRoute> routes = Arrays.asList(
+      DirectionsRoute
+        .builder()
+        .distance(1.2)
+        .duration(7.8)
+        .build()
+    );
+    Map<String, JsonElement> unrecognizedProperties = Collections.singletonMap("ccc", new JsonPrimitive("ddd"));
     DirectionsResponse response = DirectionsResponse.builder()
       .code("100")
-      .routes(new ArrayList<DirectionsRoute>())
+      .routes(routes)
+      .message("Message")
+      .metadata(metadata)
+      .uuid("uuid")
+      .waypoints(waypoints)
+      .unrecognizedJsonProperties(unrecognizedProperties)
       .build();
+
     assertNotNull(response);
+   assertEquals("100", response.code());
+   assertEquals("Message", response.message());
+   assertEquals(1, response.routes().size());
+   assertEquals(metadata, response.metadata());
+   assertEquals("uuid", response.uuid());
+   assertEquals(waypoints, response.waypoints());
+   assertEquals(unrecognizedProperties, response.getUnrecognizedJsonProperties());
   }
 
   @Test
@@ -88,16 +122,33 @@ public void accessUnrecognizedProperties() throws Exception {
     assertNull(notExistingProperty);
   }
 
+  @Test
+  public void accessUnrecognizedJsonProperties() throws Exception {
+    JsonObject directionsResponseJson = readJsonObject(DIRECTIONS_V5_PRECISION6_FIXTURE_ARTIFICIAL_FIELDS);
+    String unrecognizedPropertyName = "testUnrecognizedProperty";
+    String unrecognizedPropertyValue = "test";
+    directionsResponseJson.add(unrecognizedPropertyName, new JsonPrimitive(unrecognizedPropertyValue));
+    Map<String, JsonElement> expected = new HashMap<>();
+    expected.put(unrecognizedPropertyName, new JsonPrimitive(unrecognizedPropertyValue));
+    DirectionsResponse response = DirectionsResponse.fromJson(directionsResponseJson.toString());
+
+    Map<String, JsonElement> actual = response.getUnrecognizedJsonProperties();
+
+    assertEquals(expected, actual);
+  }
+
   @Test
   public void noUnrecognizedProperties() throws Exception {
     JsonObject directionsResponseJson = readJsonObject(DIRECTIONS_V5_PRECISION6_FIXTURE_ARTIFICIAL_FIELDS);
     DirectionsResponse response = DirectionsResponse.fromJson(directionsResponseJson.toString());
 
     JsonElement value = response.getUnrecognizedProperty("");
     Set<String> propertiesNames = response.getUnrecognizedPropertiesNames();
+    Map<String, JsonElement> jsonProperties = response.getUnrecognizedJsonProperties();
 
     assertNull(value);
     assertEquals(0, propertiesNames.size());
+    assertNull(jsonProperties);
   }
 
   @Test

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

@@ -3,12 +3,16 @@
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNotNull;
 
+import com.google.gson.JsonElement;
+import com.google.gson.JsonPrimitive;
 import com.mapbox.core.TestUtils;
 import org.junit.Test;
 
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 
 public class LegAnnotationTest extends TestUtils {
 
@@ -20,12 +24,15 @@ public void sanity() throws Exception {
       .distance(new ArrayList<Double>())
       .duration(new ArrayList<Double>())
       .speed(new ArrayList<Double>())
+      .unrecognizedJsonProperties(new HashMap<>())
       .build();
     assertNotNull(annotation);
   }
 
   @Test
   public void testSerializable() throws Exception {
+    Map<String, JsonElement> unrecognizedProperties = new HashMap<>();
+    unrecognizedProperties.put("aaa", new JsonPrimitive("bbb"));
     List<Double> distance = new ArrayList<>();
     distance.add(20d);
     distance.add(40d);
@@ -36,13 +43,16 @@ public void testSerializable() throws Exception {
       .distance(distance)
       .duration(new ArrayList<Double>())
       .speed(new ArrayList<Double>())
+      .unrecognizedJsonProperties(unrecognizedProperties)
       .build();
     byte[] serialized = TestUtils.serialize(annotation);
     assertEquals(annotation, deserialize(serialized, LegAnnotation.class));
   }
 
   @Test
   public void testToFromJson1() {
+    Map<String, JsonElement> unrecognizedProperties = new HashMap<>();
+    unrecognizedProperties.put("aaa", new JsonPrimitive("bbb"));
 
     List<Double> distanceList = Arrays.asList(
       4.294596842089401,
@@ -101,6 +111,7 @@ public void testToFromJson1() {
       .duration(durationList)
       .speed(speedList)
       .congestion(congestionList)
+      .unrecognizedJsonProperties(unrecognizedProperties)
       .build();
 
 

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

@@ -0,0 +1,75 @@
+package com.mapbox.api.directions.v5.utils;
+
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonPrimitive;
+import com.mapbox.auto.value.gson.SerializableJsonElement;
+import org.junit.Assert;
+import org.junit.Test;
+
+import java.util.HashMap;
+import java.util.Map;
+
+public class UnrecognizedPropertiesUtilsTest {
+
+  @Test
+  public void fromSerializableProperties_nullProperties() {
+    Map<String, JsonElement> actual = UnrecognizedPropertiesUtils.fromSerializableProperties(null);
+    Assert.assertNull(actual);
+  }
+
+  @Test
+  public void fromSerializableProperties_emptyProperties() {
+    Map<String, JsonElement> actual = UnrecognizedPropertiesUtils.fromSerializableProperties(
+      new HashMap<>()
+    );
+    Assert.assertEquals(0, actual.size());
+  }
+
+  @Test
+  public void fromSerializableProperties_hasProperties() {
+    final JsonObject propertyValue = new JsonObject();
+    propertyValue.add("key", new JsonPrimitive("value"));
+    final Map<String, SerializableJsonElement> properties = new HashMap<>();
+    properties.put("aaa", new SerializableJsonElement(propertyValue));
+    properties.put("bbb", new SerializableJsonElement(new JsonObject()));
+    Map<String, JsonElement> expected = new HashMap<>();
+    expected.put("aaa", propertyValue);
+    expected.put("bbb", new JsonObject());
+    final Map<String, JsonElement> actual = UnrecognizedPropertiesUtils.fromSerializableProperties(
+      properties
+    );
+    Assert.assertEquals(expected, actual);
+  }
+
+  @Test
+  public void toSerializableProperties_nullProperties() {
+    Map<String, SerializableJsonElement> actual = UnrecognizedPropertiesUtils.toSerializableProperties(null);
+    Assert.assertNull(actual);
+  }
+
+  @Test
+  public void toSerializableProperties_emptyProperties() {
+    Map<String, SerializableJsonElement> actual = UnrecognizedPropertiesUtils.toSerializableProperties(
+      new HashMap<>()
+    );
+    Assert.assertEquals(0, actual.size());
+  }
+
+  @Test
+  public void toSerializableProperties_hasProperties() {
+    final JsonObject propertyValue = new JsonObject();
+    propertyValue.add("key", new JsonPrimitive("value"));
+    final Map<String, JsonElement> properties = new HashMap<>();
+    properties.put("aaa", propertyValue);
+    properties.put("bbb", new JsonObject());
+    Map<String, SerializableJsonElement> expected = new HashMap<>();
+    expected.put("aaa", new SerializableJsonElement(propertyValue));
+    expected.put("bbb", new SerializableJsonElement(new JsonObject()));
+    final Map<String, SerializableJsonElement> actual = UnrecognizedPropertiesUtils.toSerializableProperties(
+      properties
+    );
+    Assert.assertEquals(expected, actual);
+  }
+
+}