Tidy up new ApiAccess token class.

Fix .gitignore for token.txt
Add JavaDoc to ApiAccess.
Create specific exception for missing access token.
Closes #2570
Closes #2563

4 files changed, 45 insertions, 6 deletions

diff --git a/android/java/.gitignore b/android/java/.gitignore
index 574d1ad73c..626b995946 100644
--- a/android/java/.gitignore
+++ b/android/java/.gitignore
@@ -21,7 +21,7 @@ MapboxGLAndroidSDK/src/main/assets/
 local.properties
 
 # Token file
-MapboxGLAndroidSDK/src/main/res/raw/token.txt
+MapboxGLAndroidSDKTestApp/src/main/res/raw/token.txt
 
 # Twitter Fabric / Crashlytics
 fabric.properties
diff --git a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ApiAccess.java b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ApiAccess.java
index bec77f7ff0..e6259cf446 100644
--- a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ApiAccess.java
+++ b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ApiAccess.java
@@ -4,6 +4,7 @@ import android.content.Context;
 import android.content.pm.ApplicationInfo;
 import android.content.pm.PackageManager;
 import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
 import android.text.TextUtils;
 
 import com.mapbox.mapboxsdk.R;
@@ -13,8 +14,23 @@ import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.InputStreamReader;
 
-public class ApiAccess {
+/**
+ * {@link ApiAccess} provides a method to load the Mapbox access token.
+ */
+public final class ApiAccess {
 
+    /**
+     * Returns the Mapbox access token set in the app resources.
+     * <p/>
+     * It will first search the application manifest for a {@link MapboxConstants#KEY_META_DATA_MANIFEST}
+     * meta-data value. If not found it will then attempt to load the access token from the
+     * {@code res/raw/token.txt} development file.
+     *
+     * @param context The {@link Context} of the {@link android.app.Activity} or {@link android.app.Fragment}.
+     * @return The Mapbox access token or null if not found.
+     * @see MapboxConstants#KEY_META_DATA_MANIFEST
+     */
+    @Nullable
     public static String getToken(@NonNull Context context) {
         String accessToken = getReleaseToken(context);
         if (TextUtils.isEmpty(accessToken)) {
@@ -23,7 +39,7 @@ public class ApiAccess {
         return accessToken;
     }
 
-    private static String getReleaseToken(@NonNull Context context){
+    private static String getReleaseToken(@NonNull Context context) {
         try {
             PackageManager packageManager = context.getPackageManager();
             ApplicationInfo appInfo = packageManager.getApplicationInfo(context.getPackageName(), PackageManager.GET_META_DATA);
@@ -37,7 +53,7 @@ public class ApiAccess {
         try {
             BufferedReader reader = new BufferedReader(new InputStreamReader(context.getResources().openRawResource(R.raw.token)));
             return reader.readLine();
-        }catch (IOException e){
+        } catch (IOException e) {
             return null;
         }
     }
diff --git a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/InvalidAccessTokenException.java b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/InvalidAccessTokenException.java
new file mode 100644
index 0000000000..d8581a6fd6
--- /dev/null
+++ b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/InvalidAccessTokenException.java
@@ -0,0 +1,18 @@
+package com.mapbox.mapboxsdk.views;
+
+import android.os.Bundle;
+
+/**
+ * A {@link InvalidAccessTokenException} is thrown by {@link MapView} when there is either no access
+ * token set before {@link MapView#onCreate(Bundle)} or an invalid access token is set in {@link MapView#setAccessToken(String)}
+ *
+ * @see MapView#onCreate(Bundle)
+ * @see MapView#setAccessToken(String)
+ */
+public class InvalidAccessTokenException extends RuntimeException {
+
+    InvalidAccessTokenException() {
+        super("Using MapView requires setting a valid access token. See the README.md");
+    }
+
+}
diff --git a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/MapView.java b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/MapView.java
index da91153de7..92ac06fd9d 100644
--- a/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/MapView.java
+++ b/android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/MapView.java
@@ -62,6 +62,7 @@ import com.mapbox.mapboxsdk.annotations.PolylineOptions;
 import com.mapbox.mapboxsdk.geometry.BoundingBox;
 import com.mapbox.mapboxsdk.geometry.LatLng;
 import com.mapbox.mapboxsdk.geometry.LatLngZoom;
+import com.mapbox.mapboxsdk.utils.ApiAccess;
 import com.mapzen.android.lost.api.LocationListener;
 import com.mapzen.android.lost.api.LocationRequest;
 import com.mapzen.android.lost.api.LocationServices;
@@ -79,7 +80,7 @@ import java.util.List;
  * You can center the map on a given coordinate, specify the size of the area you want to display,
  * and style the features of the map to fit your application's use case.
  * <p/>
- * Use of {@link MapView} requires a Mapbox API access token.
+ * Use of {@code MapView} requires a Mapbox API access token.
  * Obtain an access token on the <a href="https://www.mapbox.com/account/apps/">Mapbox account page</a>.
  * <p/>
  * <strong>Warning:</strong> Please note that you are responsible for getting permission to use the map data,
@@ -1503,7 +1504,7 @@ public final class MapView extends FrameLayout implements LocationListener, Comp
     // Checks if the given token is valid
     private void validateAccessToken(String accessToken) {
         if (TextUtils.isEmpty(accessToken) || (!accessToken.startsWith("pk.") && !accessToken.startsWith("sk."))) {
-            throw new RuntimeException("Using MapView requires setting a valid access token. See the README.md");
+            throw new InvalidAccessTokenException();
         }
     }
 
@@ -1512,9 +1513,13 @@ public final class MapView extends FrameLayout implements LocationListener, Comp
      * <p/>
      * You must set a valid access token before you call {@link MapView#onCreate(Bundle)}
      * or an exception will be thrown.
+     * <p/>
+     * You can use {@link ApiAccess#getToken(Context)} to load an access token from your
+     * application's manifest.
      *
      * @param accessToken Your public Mapbox access token.
      * @see MapView#onCreate(Bundle)
+     * @see ApiAccess#getToken(Context)
      */
     @UiThread
     public void setAccessToken(@NonNull String accessToken) {