[android] - add javadoc URI supported protocols

5 files changed, 335 insertions, 23 deletions

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
index a8b9de62eb..f2de07bdd0 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
@@ -118,7 +118,25 @@ public class GeoJsonSource extends Source {
   }
 
   /**
-   * Create a GeoJsonSource from a geo json file
+   * Create a GeoJsonSource from a geo json URI
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param id  the source id
    * @param uri unique resource identifier
@@ -130,7 +148,25 @@ public class GeoJsonSource extends Source {
   }
 
   /**
-   * Create a GeoJsonSource from a geo json file and non-default GeoJsonOptions
+   * Create a GeoJsonSource from a geo json URI and non-default GeoJsonOptions
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param id      the source id
    * @param uri     remote json file
@@ -286,13 +322,30 @@ public class GeoJsonSource extends Source {
   }
 
   /**
-   * Updates the uri
+   * Updates the URI of the source.
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
-   * @param url the GeoJSON FeatureCollection uri
+   * @param uri the GeoJSON FeatureCollection uri
    */
-  public void setUri(@NonNull URI url) {
-    checkThread();
-    setUrl(url.toString());
+  public void setUri(@NonNull URI uri) {
+    setUri(uri.toString());
   }
 
   /**
@@ -308,7 +361,25 @@ public class GeoJsonSource extends Source {
   }
 
   /**
-   * Updates the url
+   * Updates the URI of the source.
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param uri the GeoJSON FeatureCollection uri
    */
@@ -319,6 +390,7 @@ public class GeoJsonSource extends Source {
 
   /**
    * @return The url or null
+   * @deprecated use {@link #getUri()} instead
    */
   @Nullable
   public String getUrl() {
@@ -327,6 +399,17 @@ public class GeoJsonSource extends Source {
   }
 
   /**
+   * Get the URI of the source.
+   *
+   * @return The uri or null
+   */
+  @Nullable
+  public String getUri() {
+    checkThread();
+    return nativeGetUrl();
+  }
+
+  /**
    * Queries the source for features.
    *
    * @param filter an optional filter expression to filter the returned Features
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/ImageSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/ImageSource.java
index 3abd62ac03..33ec6a74cb 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/ImageSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/ImageSource.java
@@ -55,7 +55,25 @@ public class ImageSource extends Source {
   }
 
   /**
-   * Create an ImageSource from coordinates and an image URL
+   * Create an ImageSource from coordinates and an image URI
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param id          The source id
    * @param coordinates The Latitude and Longitude of the four corners of the image
@@ -74,7 +92,7 @@ public class ImageSource extends Source {
    * @param coordinates The Latitude and Longitude of the four corners of the image
    * @param bitmap      A Bitmap image
    */
-  public ImageSource(String id, LatLngQuad coordinates, @NonNull android.graphics.Bitmap bitmap) {
+  public ImageSource(String id, LatLngQuad coordinates, @NonNull Bitmap bitmap) {
     super();
     initialize(id, coordinates);
     setImage(bitmap);
@@ -117,16 +135,53 @@ public class ImageSource extends Source {
   }
 
   /**
-   * Updates the source image uri
+   * Updates the source image URI.
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
-   * @param uri An Image url
+   * @param uri An Image uri
    */
   public void setUri(@NonNull URI uri) {
-    setUrl(uri.toString());
+    checkThread();
+    nativeSetUrl(uri.toString());
   }
 
   /**
-   * Updates the source image uri
+   * Updates the source image URI.
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param uri An image uri
    */
@@ -164,7 +219,9 @@ public class ImageSource extends Source {
 
   /**
    * @return The url or null
+   * @deprecated use {@link #getUri()} instead
    */
+  @Deprecated
   @Nullable
   public String getUrl() {
     checkThread();
@@ -172,6 +229,17 @@ public class ImageSource extends Source {
   }
 
   /**
+   * Get the source URI.
+   *
+   * @return The uri or null
+   */
+  @Nullable
+  public String getUri() {
+    checkThread();
+    return nativeGetUrl();
+  }
+
+  /**
    * Updates the latitude and longitude of the four corners of the image
    *
    * @param latLngQuad latitude and longitude of the four corners of the image
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterDemSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterDemSource.java
index d074592ffb..9e360c46c7 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterDemSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterDemSource.java
@@ -40,7 +40,25 @@ public class RasterDemSource extends Source {
   }
 
   /**
-   * Create the raster dem source from an URI
+   * Create the raster dem source from an URI.
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param id  the source id
    * @param uri the source uri
@@ -51,6 +69,24 @@ public class RasterDemSource extends Source {
 
   /**
    * Create the raster dem source from an URI
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param id  the source id
    * @param uri the source uri
@@ -62,6 +98,24 @@ public class RasterDemSource extends Source {
 
   /**
    * Create the raster source from an URL with a specific tile size
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param id       the source id
    * @param uri     the source url
@@ -107,6 +161,8 @@ public class RasterDemSource extends Source {
   }
 
   /**
+   * Get the source URI.
+   *
    * @return The uri or null
    */
   @Nullable
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java
index ff8148d3e2..829226cdde 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java
@@ -37,7 +37,25 @@ public class RasterSource extends Source {
   }
 
   /**
-   * Create the raster source from an URI
+   * Create the raster source from an URI.
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param id  the source id
    * @param uri the source uri
@@ -47,7 +65,25 @@ public class RasterSource extends Source {
   }
 
   /**
-   * Create the raster source from an URI
+   * Create the raster source from an URI.
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param id  the source id
    * @param uri the source uri
@@ -58,10 +94,28 @@ public class RasterSource extends Source {
   }
 
   /**
-   * Create the raster source from an URL with a specific tile size
+   * Create the raster source from an URI with a specific tile size.
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param id       the source id
-   * @param uri      the source url
+   * @param uri      the source uri
    * @param tileSize the tile size
    */
   public RasterSource(String id, String uri, int tileSize) {
@@ -94,13 +148,26 @@ public class RasterSource extends Source {
 
   /**
    * @return The url or null
+   * @deprecated use {@link #getUri()} instead
    */
   @Nullable
+  @Deprecated
   public String getUrl() {
     checkThread();
     return nativeGetUrl();
   }
 
+  /**
+   * Get the source URI.
+   *
+   * @return The uri or null
+   */
+  @Nullable
+  public String getUri() {
+    checkThread();
+    return nativeGetUrl();
+  }
+
   @Keep
   protected native void initialize(String layerId, Object payload, int tileSize);
 
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java
index 20f7f50756..d847418d64 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java
@@ -46,17 +46,53 @@ public class VectorSource extends Source {
   }
 
   /**
-   * Create a vector source from a uri pointing to a TileJSON resource
+   * Create a vector source from an URI.
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param id  the source id
-   * @param uri the TileJSON resource url
+   * @param uri the TileJSON resource uri
    */
   public VectorSource(String id, Uri uri) {
     this(id, uri.toString());
   }
 
   /**
-   * Create a vector source from a uri
+   * Create a vector source from an URI.
+   * <p>
+   * An URI is a combination of a protocol and a resource path.
+   * The following URI protocol schemes are supported:
+   * </p>
+   * <ul>
+   * <li>http://</li>
+   * <ul>
+   * <li>load resources using HyperText Transfer Protocol</li>
+   * </ul>
+   * <li>file://</li>
+   * <ul>
+   * <li>load resources from the Android file system</li>
+   * </ul>
+   * <li>asset://</li>
+   * <ul>
+   * <li>load resources from the binary packaged assets folder</li>
+   * </ul>
+   * </ul>
    *
    * @param id  the source id
    * @param uri the uri
@@ -67,7 +103,7 @@ public class VectorSource extends Source {
   }
 
   /**
-   * Create a vector source from a tilset
+   * Create a vector source from a tileset
    *
    * @param id      the source id
    * @param tileSet the tileset
@@ -106,6 +142,8 @@ public class VectorSource extends Source {
   }
 
   /**
+   * Get the source URI.
+   *
    * @return The uri or null
    */
   @Nullable