Merge "Fix WebViewDatabase javadoc." into nyc-mr2-dev

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
+     * Stores HTTP authentication credentials for a given host and realm to the {@link WebViewDatabase}
-     * method is intended to be used with
+     * instance.
-     * {@link WebViewClient#onReceivedHttpAuthRequest}.
+     * <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.
+     * Retrieves HTTP authentication credentials for a given host and realm from the {@link
-     * This method is intended to be used with
+     * WebViewDatabase} instance.
-     * {@link WebViewClient#onReceivedHttpAuthRequest}.
      *
      * @param host the host to which the credentials apply
      * @param realm the realm to which the credentials apply

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