weblayer: improve docs on NavigationController

This also changes the client library to throw (runtime) exceptions
in certain scenarios. This is an incompatible change to the client
library, but prior to this we would have hit DCHECKs, and Alihan
agreed with this change, so I'm going for it.

BUG=none
TEST=none

Change-Id: I9ee43b8c61c999245ab5a8bd4e90a21b8aca42e6
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2124299Reviewed-by: John Abd-El-Malek <jam@chromium.org>
Commit-Queue: Scott Violet <sky@chromium.org>
Cr-Commit-Position: refs/heads/master@{#754208}

weblayer/browser/android/javatests/src/org/chromium/weblayer/test/NavigationTest.java

@@ -326,9 +326,6 @@ public class NavigationTest {
             assertEquals("Page A", navigationController.getNavigationEntryTitle(0));
             assertEquals("Page B", navigationController.getNavigationEntryTitle(1));
             assertEquals("Page C", navigationController.getNavigationEntryTitle(2));
-
-            // An out of bounds index will return an empty string.
-            assertEquals("", navigationController.getNavigationEntryTitle(1234));
         });
     }
 

weblayer/public/java/org/chromium/weblayer/NavigationController.java

@@ -68,8 +68,16 @@ public class NavigationController {
         }
     }
 
-    public void goBack() {
+    /**
+     * Navigates to the previous navigation.
+     *
+     * @throws IndexOutOfBoundsException If {@link #canGoBack} returns false.
+     */
+    public void goBack() throws IndexOutOfBoundsException {
         ThreadCheck.ensureOnUiThread();
+        if (!canGoBack()) {
+            throw new IndexOutOfBoundsException();
+        }
         try {
             mNavigationController.goBack();
         } catch (RemoteException e) {
@@ -77,8 +85,16 @@ public class NavigationController {
         }
     }
 
-    public void goForward() {
+    /**
+     * Navigates to the next navigation.
+     *
+     * @throws IndexOutOfBoundsException If {@link #canGoForward} returns false.
+     */
+    public void goForward() throws IndexOutOfBoundsException {
         ThreadCheck.ensureOnUiThread();
+        if (!canGoForward()) {
+            throw new IndexOutOfBoundsException();
+        }
         try {
             mNavigationController.goForward();
         } catch (RemoteException e) {
@@ -86,6 +102,11 @@ public class NavigationController {
         }
     }
 
+    /**
+     * Returns true if there is a navigation before the current one.
+     *
+     * @return Whether there is a navigation before the current one.
+     */
     public boolean canGoBack() {
         ThreadCheck.ensureOnUiThread();
         try {
@@ -95,6 +116,11 @@ public class NavigationController {
         }
     }
 
+    /**
+     * Returns true if there is a navigation after the current one.
+     *
+     * @return Whether there is a navigation after the current one.
+     */
     public boolean canGoForward() {
         ThreadCheck.ensureOnUiThread();
         try {
@@ -105,13 +131,20 @@ public class NavigationController {
     }
 
     /**
+     * Navigates to the entry at {@link index}.
+     *
+     * @throws IndexOutOfBoundsException If index is not between 0 and {@link
+     *         getNavigationListCurrentIndex}.
+     * @throws IndexOutOfBoundsException
+     *
      * @since 81
      */
-    public void goToIndex(int index) {
+    public void goToIndex(int index) throws IndexOutOfBoundsException {
         ThreadCheck.ensureOnUiThread();
         if (WebLayer.getSupportedMajorVersionInternal() < 81) {
             throw new UnsupportedOperationException();
         }
+        checkNavigationIndex(index);
         try {
             mNavigationController.goToIndex(index);
         } catch (RemoteException e) {
@@ -119,6 +152,9 @@ public class NavigationController {
         }
     }
 
+    /**
+     * Reloads the current entry. Does nothing if there are no navigations.
+     */
     public void reload() {
         ThreadCheck.ensureOnUiThread();
         try {
@@ -128,6 +164,9 @@ public class NavigationController {
         }
     }
 
+    /**
+     * Stops in progress loading. Does nothing if not in the process of loading.
+     */
     public void stop() {
         ThreadCheck.ensureOnUiThread();
         try {
@@ -137,6 +176,11 @@ public class NavigationController {
         }
     }
 
+    /**
+     * Returns the number of navigations entries.
+     *
+     * @return The number of navigation entries, 0 if empty.
+     */
     public int getNavigationListSize() {
         ThreadCheck.ensureOnUiThread();
         try {
@@ -146,6 +190,11 @@ public class NavigationController {
         }
     }
 
+    /**
+     * Returns the index of the current navigation, -1 if there are no navigations.
+     *
+     * @return The index of the current navigation.
+     */
     public int getNavigationListCurrentIndex() {
         ThreadCheck.ensureOnUiThread();
         try {
@@ -155,8 +204,15 @@ public class NavigationController {
         }
     }
 
+    /**
+     * Returns the uri to display for the navigation at index.
+     *
+     * @param index The index of the navigation.
+     * @throws IndexOutOfBoundsException If index is not between 0 and {@link
+     *         getNavigationListCurrentIndex}.
+     */
     @NonNull
-    public Uri getNavigationEntryDisplayUri(int index) {
+    public Uri getNavigationEntryDisplayUri(int index) throws IndexOutOfBoundsException {
         ThreadCheck.ensureOnUiThread();
         try {
             return Uri.parse(mNavigationController.getNavigationEntryDisplayUri(index));
@@ -165,15 +221,26 @@ public class NavigationController {
         }
     }
 
+    private void checkNavigationIndex(int index) throws IndexOutOfBoundsException {
+        if (index < 0 || index >= getNavigationListSize()) {
+            throw new IndexOutOfBoundsException();
+        }
+    }
+
     /**
+     * Returns the title of the navigation entry at the supplied index.
+     *
+     * @throws IndexOutOfBoundsException If index is not between 0 and {@link
+     *         getNavigationListCurrentIndex}.
      * @since 81
      */
     @NonNull
-    public String getNavigationEntryTitle(int index) {
+    public String getNavigationEntryTitle(int index) throws IndexOutOfBoundsException {
         ThreadCheck.ensureOnUiThread();
         if (WebLayer.getSupportedMajorVersionInternal() < 81) {
             throw new UnsupportedOperationException();
         }
+        checkNavigationIndex(index);
         try {
             return mNavigationController.getNavigationEntryTitle(index);
         } catch (RemoteException e) {