chore: improve missing config error messages (#1038)

The Amplify documentation suggests to configure the library with this
call:
```kotlin
Amplify.configure(applicationContext)
```
When configured in this way, the library will attempt to load a file
from the the user's application project. The file is expected to live at
`app/src/main/res/raw/amplifyconfiguration.json`.

If this file is *not* present, the previous error message was not very
helpful. This commit updates the error message, to give the user a
direct call to action.

This PR also updates a few related resource loading messages, to make
their error cases more clear.

Author: jamesonwilliams

core/src/main/java/com/amplifyframework/core/AmplifyConfiguration.java

@@ -112,7 +112,7 @@ public static AmplifyConfiguration fromJson(@NonNull JSONObject json) throws Amp
     @SuppressWarnings("WeakerAccess")
     @NonNull
     public static AmplifyConfiguration fromConfigFile(@NonNull Context context) throws AmplifyException {
-        return builder(context, Resources.getRawResourceId(context, DEFAULT_IDENTIFIER)).build();
+        return builder(context).build();
     }
 
     /**
@@ -206,7 +206,16 @@ public CategoryConfiguration forCategoryType(@NonNull CategoryType categoryType)
      */
     @NonNull
     public static Builder builder(@NonNull Context context) throws AmplifyException {
-        return builder(context, Resources.getRawResourceId(context, DEFAULT_IDENTIFIER));
+        try {
+            @RawRes final int resourceId = Resources.getRawResourceId(context, DEFAULT_IDENTIFIER);
+            return builder(context, resourceId);
+        } catch (Resources.ResourceLoadingException resourceLoadingException) {
+            throw new AmplifyException(
+                "Failed to load the " + DEFAULT_IDENTIFIER + " configuration file.", resourceLoadingException,
+                "Is there an Amplify configuration file present in your app project, under " +
+                    "./app/src/main/res/raw/" + DEFAULT_IDENTIFIER + "?"
+            );
+        }
     }
 
     /**
@@ -219,11 +228,18 @@ public static Builder builder(@NonNull Context context) throws AmplifyException
      * @throws AmplifyException If there is a problem in the config file
      */
     @NonNull
-    public static Builder builder(
-            @NonNull Context context,
-            @RawRes int configFileResourceId
-    ) throws AmplifyException {
-        return builder(Resources.readJsonResourceFromId(Objects.requireNonNull(context), configFileResourceId));
+    public static Builder builder(@NonNull Context context, @RawRes int configFileResourceId)
+            throws AmplifyException {
+        Objects.requireNonNull(context);
+        try {
+            return builder(Resources.readJsonResourceFromId(context, configFileResourceId));
+        } catch (Resources.ResourceLoadingException resourceLoadingException) {
+            throw new AmplifyException(
+                "Failed to read JSON from resource = " + configFileResourceId, resourceLoadingException,
+                "If you are attempting to load a custom configuration file, please ensure that it exists " +
+                    "in your application project under app/src/main/res/raw/<YOUR_CUSTOM_CONFIG_FILE>."
+            );
+        }
     }
 
     /**
@@ -298,4 +314,3 @@ public AmplifyConfiguration build() {
         }
     }
 }
-

core/src/main/java/com/amplifyframework/core/Resources.java

@@ -19,8 +19,6 @@
 import android.content.res.Resources.NotFoundException;
 import androidx.annotation.RawRes;
 
-import com.amplifyframework.AmplifyException;
-
 import org.json.JSONException;
 import org.json.JSONObject;
 
@@ -31,25 +29,21 @@
  * A utility to read resource files.
  */
 public final class Resources {
-
-    private Resources() { }
+    private Resources() {}
 
     /**
      * Obtains the raw resource ID for the given resource identifier.
      * @param context An Android Context
      * @param identifier Name of a raw resource
      * @return ID of the raw resource
-     * @throws AmplifyException if the specified raw resource does not exist
+     * @throws ResourceLoadingException if the specified raw resource does not exist
      */
     @RawRes
-    public static int getRawResourceId(Context context, String identifier) throws AmplifyException {
+    public static int getRawResourceId(Context context, String identifier) throws ResourceLoadingException {
         try {
             return context.getResources().getIdentifier(identifier, "raw", context.getPackageName());
-        } catch (Exception exception) {
-            throw new AmplifyException(
-                    "Failed to find " + identifier + ".",
-                    exception, "Please check that it exists."
-            );
+        } catch (Exception lookupError) {
+            throw new ResourceLoadingException("No such resource with identifier " + identifier, lookupError);
         }
     }
 
@@ -58,9 +52,10 @@ public static int getRawResourceId(Context context, String identifier) throws Am
      * @param context An Android Context
      * @param identifier Name of a raw resource
      * @return JSON Object equivalent of the raw resource
-     * @throws AmplifyException If resource with given ID does not exist or cannot be read
+     * @throws ResourceLoadingException If resource with given ID does not exist or cannot be read
      */
-    public static JSONObject readJsonResource(Context context, String identifier) throws AmplifyException {
+    public static JSONObject readJsonResource(Context context, String identifier)
+            throws ResourceLoadingException {
         return readJsonResourceFromId(context, getRawResourceId(context, identifier));
     }
 
@@ -69,18 +64,16 @@ public static JSONObject readJsonResource(Context context, String identifier) th
      * @param context An Android Context
      * @param resourceId ID of a raw resource
      * @return JSON Object equivalent of the raw resource
-     * @throws AmplifyException If resource with given ID does not exist or cannot be read
+     * @throws ResourceLoadingException If resource with given ID does not exist or cannot be read
      */
-    public static JSONObject readJsonResourceFromId(Context context, @RawRes int resourceId) throws AmplifyException {
+    public static JSONObject readJsonResourceFromId(Context context, @RawRes int resourceId)
+            throws ResourceLoadingException {
         InputStream inputStream;
 
         try {
             inputStream = context.getResources().openRawResource(resourceId);
-        } catch (NotFoundException exception) {
-            throw new AmplifyException(
-                    "Failed to find the resource with ID " + resourceId + ".",
-                    exception, "Please check that it has been created."
-            );
+        } catch (NotFoundException notFoundError) {
+            throw new ResourceLoadingException("No such resource with ID = " + resourceId, notFoundError);
         }
 
         final Scanner in = new Scanner(inputStream);
@@ -92,11 +85,26 @@ public static JSONObject readJsonResourceFromId(Context context, @RawRes int res
 
         try {
             return new JSONObject(sb.toString());
-        } catch (JSONException jsonError) {
-            throw new AmplifyException(
-                    "Failed to read the resource with ID " + resourceId + ".",
-                    jsonError, "Please check that it is correctly formed."
+        } catch (JSONException badJsonError) {
+            throw new ResourceLoadingException(
+                "Failed to read the resource with ID " + resourceId + ".", badJsonError
             );
         }
     }
+
+    /**
+     * Indicates that a requested resource cannot be loaded.
+     */
+    public static final class ResourceLoadingException extends Exception {
+        private static final long serialVersionUID = 1;
+
+        /**
+         * Constructs a new resource loading exception.
+         * @param failureRationale A rationale for the failure
+         * @param rootCause A root cause for the failure
+         */
+        public ResourceLoadingException(String failureRationale, Throwable rootCause) {
+            super(failureRationale, rootCause);
+        }
+    }
 }

core/src/main/java/com/amplifyframework/devmenu/EnvironmentInfo.java

@@ -76,7 +76,15 @@ public String getPluginVersions() {
      */
     public String getDeveloperEnvironmentInfo(@NonNull Context context) throws AmplifyException {
         Context appContext = Objects.requireNonNull(context).getApplicationContext();
-        JSONObject envInfo = Resources.readJsonResource(appContext, DEV_ENV_INFO_FILE_NAME);
+        final JSONObject envInfo;
+        try {
+            envInfo = Resources.readJsonResource(appContext, DEV_ENV_INFO_FILE_NAME);
+        } catch (Resources.ResourceLoadingException resourceLoadingException) {
+            throw new AmplifyException(
+                "Failed to find " + DEV_ENV_INFO_FILE_NAME + ".", resourceLoadingException,
+                "Please ensure it is present in your project."
+            );
+        }
         StringBuilder formattedEnvInfo = new StringBuilder();
         for (String envItem : devEnvironmentItems.keySet()) {
             if (envInfo.has(envItem)) {