Conveniences to Position model (#309)

* add a Position.fromLngLat() method

* add warning if lat or lon values seem out of range

Author: zugaldia

mapbox/app/src/main/java/com/mapbox/services/android/testapp/MainActivity.java

@@ -37,6 +37,7 @@
 import com.mapbox.services.android.testapp.turf.TurfMidpointActivity;
 import com.mapbox.services.android.testapp.utils.MapMatchingActivity;
 import com.mapbox.services.android.testapp.utils.SimplifyPolylineActivity;
+import com.mapbox.services.commons.models.Position;
 
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -169,6 +170,10 @@ protected void onCreate(Bundle savedInstanceState) {
     Log.d(LOG_TAG, "MAS version name: " + BuildConfig.VERSION_NAME);
     Log.d(LOG_TAG, "MAS version code: " + BuildConfig.VERSION_CODE);
 
+    // Check Position warnings are working
+    Log.d(LOG_TAG, "The following Position warnings are intentional:");
+    Position.fromLngLat(185, 95);
+
     // RecyclerView
     recyclerView = (RecyclerView) findViewById(R.id.recycler_view);
     recyclerView.setHasFixedSize(true);

mapbox/libjava-core/src/main/java/com/mapbox/services/Constants.java

@@ -4,6 +4,11 @@
 
 public class Constants {
 
+  /**
+   * Default locale
+   */
+  public static final Locale DEFAULT_LOCALE = Locale.US;
+
   /**
    * User agent for HTTP requests
    */

mapbox/libjava-core/src/main/java/com/mapbox/services/commons/models/Position.java

@@ -1,18 +1,25 @@
 package com.mapbox.services.commons.models;
 
+import com.mapbox.services.Constants;
+
+import java.util.logging.Logger;
+
 /**
  * Represents a position defined by a longitude, latitude, and optionally, an altitude.
  *
  * @since 1.0.0
  */
 public class Position {
 
+  private static final Logger logger = Logger.getLogger(Position.class.getSimpleName());
+
   private final double longitude;
   private final double latitude;
   private final double altitude;
 
   /**
-   * Private Constructor
+   * Private constructor. It'll emit a warning if either latitude or longitude seem
+   * to be out of range.
    *
    * @param longitude double value with position's longitude.
    * @param latitude  double value with position's latitude.
@@ -23,6 +30,22 @@ private Position(double longitude, double latitude, double altitude) {
     this.longitude = longitude;
     this.latitude = latitude;
     this.altitude = altitude;
+
+    if (latitude < -90 || latitude > 90) {
+      // Checks the latitude value is within range or provide a warning otherwise
+      logger.warning(String.format(Constants.DEFAULT_LOCALE,
+        "Latitude value seems to be out of range (found: %f, expected: [-90, 90]). "
+          + "Did you accidentally reverse the longitude/latitude order?",
+        latitude));
+    }
+
+    if (longitude < -180 || longitude > 180) {
+      // Checks the longitude value is within range or provide a warning otherwise
+      logger.warning(String.format(Constants.DEFAULT_LOCALE,
+        "Longitude value seems to be out of range (found: %f, expected: [-180, 180]). "
+        + "Did you accidentally reverse the longitude/latitude order?",
+        longitude));
+    }
   }
 
   /**
@@ -103,6 +126,20 @@ public static Position fromCoordinates(double[] coordinates) {
     }
   }
 
+  /**
+   * Builds a {@link Position} from a double longitude and latitude. Identical to
+   * {@link #fromCoordinates(double, double)} but more explicit about the right order
+   * for the longitude and latitude parameters.
+   *
+   * @param longitude double longitude value.
+   * @param latitude  double latitude value.
+   * @return {@link Position}.
+   * @since 2.0.0
+   */
+  public static Position fromLngLat(double longitude, double latitude) {
+    return Position.fromCoordinates(longitude, latitude);
+  }
+
   /**
    * Checks if a position has an altitude value.
    *