add RouteLeg#notifications

CHANGELOG.md

@@ -3,6 +3,7 @@
 Mapbox welcomes participation and contributions from everyone.
 
 ### main
+- Added `RouteLeg#notifications`.
 
 ### v6.11.0 - March 03, 2023
 - No additional changes

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

@@ -0,0 +1,47 @@
+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.api.directions.v5.models.Notification;
+import com.mapbox.api.directions.v5.models.RouteOptions;
+import com.mapbox.sample.BuildConfig;
+import retrofit2.Response;
+
+import java.io.IOException;
+import java.util.Arrays;
+import java.util.List;
+
+public class BasicRouteNotification {
+
+  public static void main(String[] args) throws IOException {
+    simpleMapboxDirectionsRequest();
+  }
+
+  private static void simpleMapboxDirectionsRequest() throws IOException {
+    MapboxDirections.Builder builder = MapboxDirections.builder();
+
+    // 1. Pass in all the required information to get a simple directions route.
+    RouteOptions routeOptions = RouteOptions.builder()
+      .user("") // the user which has route notifications enabled
+      .profile(DirectionsCriteria.PROFILE_DRIVING_TRAFFIC)
+      .coordinates("-115.5747924943478,49.58740426100405;-115.33330133850265,49.444367698479994")
+      .steps(true)
+      .overview(DirectionsCriteria.OVERVIEW_FULL)
+      .geometries(DirectionsCriteria.GEOMETRY_POLYLINE6)
+      .excludeList(Arrays.asList(DirectionsCriteria.EXCLUDE_UNPAVED))
+      .build();
+    builder.routeOptions(routeOptions);
+    builder.accessToken(BuildConfig.MAPBOX_ACCESS_TOKEN);
+
+    // 2. That's it! Now execute the command and get the response.
+    Response<DirectionsResponse> response = builder.build().executeCall();
+
+    // 3. Log information from the response
+    System.out.println("Check that the GET response is successful " + response.isSuccessful());
+    if (response.isSuccessful()) {
+      List<Notification> notifications = response.body().routes().get(0).legs().get(0).notifications();
+      System.out.println("Notifications: " + notifications);
+    }
+  }
+}

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

@@ -3,6 +3,9 @@
 import androidx.annotation.IntDef;
 import androidx.annotation.StringDef;
 import com.mapbox.api.directions.v5.models.Amenity;
+import com.mapbox.api.directions.v5.models.Notification;
+import com.mapbox.api.directions.v5.models.RouteLeg;
+import com.mapbox.api.directions.v5.models.RouteOptions;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -468,6 +471,59 @@ public final class DirectionsCriteria {
    */
   public static final String AMENITY_TYPE_FAX = "FAX";
 
+  /**
+   * Violation notification type. {@link Notification#type()} will have this value
+   * if some request parameters were violated.
+   */
+  public static final String NOTIFICATION_TYPE_VIOLATION = "violation";
+
+  /**
+   * Max height notification subtype of type {@link DirectionsCriteria#NOTIFICATION_TYPE_VIOLATION}.
+   * {@link Notification#subtype()} will have this value
+   * if {@link RouteOptions#maxHeight()} parameter is violated.
+   */
+  public static final String NOTIFICATION_SUBTYPE_MAX_HEIGHT = "maxHeight";
+
+  /**
+   * Max width notification subtype of type {@link DirectionsCriteria#NOTIFICATION_TYPE_VIOLATION}.
+   * {@link Notification#subtype()} will have this value
+   * if {@link RouteOptions#maxWidth()} parameter is violated.
+   */
+  public static final String NOTIFICATION_SUBTYPE_MAX_WIDTH = "maxWidth";
+
+  /**
+   * Max weight notification subtype of type {@link DirectionsCriteria#NOTIFICATION_TYPE_VIOLATION}.
+   * {@link Notification#subtype()} will have this value
+   * if {@link RouteOptions#maxWeight()} parameter is violated.
+   */
+  public static final String NOTIFICATION_SUBTYPE_MAX_WEIGHT = "maxWeight";
+
+  /**
+   * Unpaved notification subtype of type {@link DirectionsCriteria#NOTIFICATION_TYPE_VIOLATION}.
+   * {@link Notification#subtype()} will have this value
+   * if {@link RouteOptions#exclude()} parameter with value
+   * {@link DirectionsCriteria#EXCLUDE_UNPAVED} is violated.
+   */
+  public static final String NOTIFICATION_SUBTYPE_UNPAVED = "unpaved";
+
+  /**
+   * Point exclusion notification subtype of type
+   * {@link DirectionsCriteria#NOTIFICATION_TYPE_VIOLATION}.
+   * {@link Notification#subtype()} will have this value
+   * if {@link RouteOptions#exclude()} parameter with point value is violated.
+   */
+  public static final String NOTIFICATION_SUBTYPE_POINT_EXCLUSION = "pointExclusion";
+
+  /**
+   * Include all notifications in the route response (see {@link RouteLeg#notifications()}).
+   */
+  public static final String NOTIFICATION_FLOW_ALL = "all";
+
+  /**
+   * Include none of the notifications in the route response (see {@link RouteLeg#notifications()}).
+   */
+  public static final String NOTIFICATION_FLOW_NONE = "none";
+
   private DirectionsCriteria() {
     //not called
   }
@@ -685,4 +741,39 @@ private DirectionsCriteria() {
   })
   public @interface AmenityTypeCriteria {
   }
+
+  /**
+   * Supported notification types. See {@link Notification#type()}.
+   */
+  @Retention(RetentionPolicy.CLASS)
+  @StringDef({
+    NOTIFICATION_TYPE_VIOLATION,
+  })
+  public @interface NotificationsTypeCriteria {
+  }
+
+  /**
+   * Supported notification subtypes. See {@link Notification#subtype()}.
+   */
+  @Retention(RetentionPolicy.CLASS)
+  @StringDef({
+    NOTIFICATION_SUBTYPE_MAX_HEIGHT,
+    NOTIFICATION_SUBTYPE_MAX_WIDTH,
+    NOTIFICATION_SUBTYPE_MAX_WEIGHT,
+    NOTIFICATION_SUBTYPE_UNPAVED,
+    NOTIFICATION_SUBTYPE_POINT_EXCLUSION,
+  })
+  public @interface NotificationsSubtypeCriteria {
+  }
+
+  /**
+   * Supported {@link RouteOptions#notifications()} parameter values.
+   */
+  @Retention(RetentionPolicy.CLASS)
+  @StringDef({
+    NOTIFICATION_FLOW_ALL,
+    NOTIFICATION_FLOW_NONE,
+  })
+  public @interface NotificationsFlowCriteria {
+  }
 }

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

@@ -0,0 +1,173 @@
+package com.mapbox.api.directions.v5.models;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import com.google.auto.value.AutoValue;
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.TypeAdapter;
+import com.google.gson.annotations.SerializedName;
+import com.mapbox.api.directions.v5.DirectionsAdapterFactory;
+import com.mapbox.api.directions.v5.DirectionsCriteria;
+
+/**
+ * Class containing information about route notification. See {@link RouteLeg#notifications()}.
+ */
+@AutoValue
+public abstract class Notification extends DirectionsJsonObject {
+
+  /**
+   * Create a new instance of this class by using the {@link Builder} class.
+   *
+   * @return this classes {@link Builder} for creating a new instance
+   */
+  public static Builder builder() {
+    return new AutoValue_Notification.Builder();
+  }
+
+  /**
+   * Notification type. Can be one of {@link DirectionsCriteria.NotificationsTypeCriteria}.
+   *
+   * @return notification type
+   */
+  @NonNull
+  @DirectionsCriteria.NotificationsTypeCriteria
+  public abstract String type();
+
+  /**
+   * Notification subtype. Can be one of {@link DirectionsCriteria.NotificationsSubtypeCriteria},
+   * depending on {@link Notification#type()}.
+   *
+   * @return notification subtype
+   */
+  @Nullable
+  @DirectionsCriteria.NotificationsSubtypeCriteria
+  public abstract String subtype();
+
+  /**
+   * Leg-wise start index of the area that violates the request parameter.
+   *
+   * @return start index
+   */
+  @SerializedName("geometry_index_start")
+  @Nullable
+  public abstract Integer geometryIndexStart();
+
+  /**
+   * Leg-wise end index of the area that violates the request parameter.
+   *
+   * @return end index
+   */
+  @SerializedName("geometry_index_end")
+  @Nullable
+  public abstract Integer geometryIndexEnd();
+
+  /**
+   * Notification details specific to {@link Notification#type()}
+   * and {@link Notification#subtype()}.
+   *
+   * @return notification details
+   */
+  @Nullable
+  public abstract NotificationDetails details();
+
+  /**
+   * Convert the current {@link Notification} to its builder holding the currently assigned
+   * values. This allows you to modify a single property and then rebuild the object resulting in
+   * an updated and modified {@link Notification}.
+   *
+   * @return a {@link Builder} with the same values set to match the ones defined
+   *   in this {@link Notification}
+   */
+  public abstract Builder toBuilder();
+
+  /**
+   * Gson type adapter for parsing Gson to this class.
+   *
+   * @param gson the built {@link Gson} object
+   * @return the type adapter for this class
+   */
+  public static TypeAdapter<Notification> typeAdapter(Gson gson) {
+    return new AutoValue_Notification.GsonTypeAdapter(gson);
+  }
+
+  /**
+   * Create a new instance of this class by passing in a formatted valid JSON String.
+   *
+   * @param json a formatted valid JSON string defining a Notification
+   * @return a new instance of this class defined by the values passed inside this static factory
+   *   method
+   */
+  public static Notification fromJson(String json) {
+    GsonBuilder gson = new GsonBuilder();
+    gson.registerTypeAdapterFactory(DirectionsAdapterFactory.create());
+    return gson.create().fromJson(json, Notification.class);
+  }
+
+  /**
+   * This builder can be used to set the values describing the {@link Notification}.
+   */
+  @AutoValue.Builder
+  public abstract static class Builder extends DirectionsJsonObject.Builder<Builder> {
+
+    /**
+     * Notification type. Can be one of {@link DirectionsCriteria.NotificationsTypeCriteria}.
+     *
+     * @param type notification type
+     * @return this builder for chaining options together
+     */
+    @NonNull
+    public abstract Builder type(
+      @NonNull @DirectionsCriteria.NotificationsTypeCriteria String type
+    );
+
+    /**
+     * Notification subtype. Can be one of {@link DirectionsCriteria.NotificationsSubtypeCriteria},
+     * depending on {@link Notification.Builder#type()}.
+     *
+     * @param subtype notification subtype
+     * @return this builder for chaining options together
+     */
+    @NonNull
+    public abstract Builder subtype(
+      @Nullable @DirectionsCriteria.NotificationsSubtypeCriteria String subtype
+    );
+
+    /**
+     * Leg-wise start index of the area that violates the request parameter.
+     *
+     * @param geometryIndexStart start index
+     * @return this builder for chaining options together
+     */
+    @SerializedName("geometry_index_start")
+    @NonNull
+    public abstract Builder geometryIndexStart(@Nullable Integer geometryIndexStart);
+
+    /**
+     * Leg-wise end index of the area that violates the request parameter.
+     *
+     * @param geometryIndexEnd end index
+     * @return this builder for chaining options together
+     */
+    @SerializedName("geometry_index_end")
+    @NonNull
+    public abstract Builder geometryIndexEnd(@Nullable Integer geometryIndexEnd);
+
+    /**
+     * Notification details.
+     *
+     * @param details notification details
+     * @return this builder for chaining options together
+     */
+    @NonNull
+    public abstract Builder details(@Nullable NotificationDetails details);
+
+    /**
+     * Build a new {@link Notification} object.
+     *
+     * @return a new {@link Notification} using the provided values in this builder
+     */
+    @NonNull
+    public abstract Notification build();
+  }
+}