From 68d2cc180f6b39f7c92045c998d02cd7d6bfa7e5 Mon Sep 17 00:00:00 2001
From: Hui Shu <hush@google.com>
Date: Mon, 29 Aug 2016 11:49:46 -0700
Subject: [PATCH] Fix WebViewDatabase javadoc.

BUG=30481165
Change-Id: Ibd14880aa25907234dd93c38b5d0f2c9e808340e
(cherry picked from commit 433fb935157a2841513dd00175e792ba92fecb56)
---
 core/java/android/webkit/WebView.java         | 28 +++++++++++++++----
 core/java/android/webkit/WebViewDatabase.java | 13 +++++++--
 2 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/core/java/android/webkit/WebView.java b/core/java/android/webkit/WebView.java
index f54edf14bbe18..3a85519542662 100644
--- a/core/java/android/webkit/WebView.java
+++ b/core/java/android/webkit/WebView.java
@@ -740,9 +740,26 @@ public class WebView extends AbsoluteLayout
     }
 
     /**
-     * Stores HTTP authentication credentials for a given host and realm. This
-     * method is intended to be used with
-     * {@link WebViewClient#onReceivedHttpAuthRequest}.
+     * Stores HTTP authentication credentials for a given host and realm to the {@link WebViewDatabase}
+     * instance.
+     * <p>
+     * To use HTTP authentication, the embedder application has to implement
+     * {@link WebViewClient#onReceivedHttpAuthRequest}, and call {@link HttpAuthHandler#proceed}
+     * with the correct username and password.
+     * <p>
+     * The embedder app can get the username and password any way it chooses, and does not have to
+     * use {@link WebViewDatabase}.
+     * <p>
+     * Notes:
+     * <li>
+     * {@link WebViewDatabase} is provided only as a convenience to store and retrieve http
+     * authentication credentials. WebView does not read from it during HTTP authentication.
+     * </li>
+     * <li>
+     * WebView does not provide a special mechanism to clear HTTP authentication credentials for
+     * implementing client logout. The client logout mechanism should be implemented by the Web site
+     * designer (such as server sending a HTTP 401 for invalidating credentials).
+     * </li>
      *
      * @param host the host to which the credentials apply
      * @param realm the realm to which the credentials apply
@@ -759,9 +776,8 @@ public class WebView extends AbsoluteLayout
     }
 
     /**
-     * Retrieves HTTP authentication credentials for a given host and realm.
-     * This method is intended to be used with
-     * {@link WebViewClient#onReceivedHttpAuthRequest}.
+     * Retrieves HTTP authentication credentials for a given host and realm from the {@link
+     * WebViewDatabase} instance.
      *
      * @param host the host to which the credentials apply
      * @param realm the realm to which the credentials apply
diff --git a/core/java/android/webkit/WebViewDatabase.java b/core/java/android/webkit/WebViewDatabase.java
index cdff41685b801..cc2c6cc348033 100644
--- a/core/java/android/webkit/WebViewDatabase.java
+++ b/core/java/android/webkit/WebViewDatabase.java
@@ -44,7 +44,7 @@ public abstract class WebViewDatabase {
      *
      * @return true if there are any saved username/password pairs
      * @see WebView#savePassword
-     * @see #clearUsernamePassworda
+     * @see #clearUsernamePassword
      * @deprecated Saving passwords in WebView will not be supported in future versions.
      */
     @Deprecated
@@ -72,7 +72,16 @@ public abstract class WebViewDatabase {
     public abstract boolean hasHttpAuthUsernamePassword();
 
     /**
-     * Clears any saved credentials for HTTP authentication.
+     * Clears any saved credentials for HTTP authentication. This method only clears the username
+     * and password stored in WebViewDatabase instance. The username and password are not read from
+     * the {@link WebViewDatabase} during {@link WebViewClient#onReceivedHttpAuthRequest}. It is up
+     * to the app to do this or not.
+     * <p>
+     * The username and password used for http authentication might be cached in the network stack
+     * itself, and are not cleared when this method is called.  WebView does not provide a special
+     * mechanism to clear HTTP authentication for implementing client logout. The client logout
+     * mechanism should be implemented by the Web site designer (such as server sending a HTTP 401
+     * for invalidating credentials).
      *
      * @see WebView#getHttpAuthUsernamePassword
      * @see WebView#setHttpAuthUsernamePassword