1/*
2 * Copyright (C) 2007 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.webkit;
18
19import android.annotation.Nullable;
20import android.content.Context;
21
22/**
23 * This class allows developers to determine whether any WebView used in the
24 * application has stored any of the following types of browsing data and
25 * to clear any such stored data for all WebViews in the application.
26 * <ul>
27 *  <li>Username/password pairs for web forms</li>
28 *  <li>HTTP authentication username/password pairs</li>
29 *  <li>Data entered into text fields (e.g. for autocomplete suggestions)</li>
30 * </ul>
31 */
32public abstract class WebViewDatabase {
33    /**
34     * @hide Since API level {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1}
35     */
36    protected static final String LOGTAG = "webviewdatabase";
37
38    public static WebViewDatabase getInstance(Context context) {
39        return WebViewFactory.getProvider().getWebViewDatabase(context);
40    }
41
42    /**
43     * Gets whether there are any saved username/password pairs for web forms.
44     * Note that these are unrelated to HTTP authentication credentials.
45     *
46     * @return {@code true} if there are any saved username/password pairs
47     * @see WebView#savePassword
48     * @see #clearUsernamePassword
49     * @deprecated Saving passwords in WebView will not be supported in future versions.
50     */
51    @Deprecated
52    public abstract boolean hasUsernamePassword();
53
54    /**
55     * Clears any saved username/password pairs for web forms.
56     * Note that these are unrelated to HTTP authentication credentials.
57     *
58     * @see WebView#savePassword
59     * @see #hasUsernamePassword
60     * @deprecated Saving passwords in WebView will not be supported in future versions.
61     */
62    @Deprecated
63    public abstract void clearUsernamePassword();
64
65    /**
66     * Gets whether there are any saved credentials for HTTP authentication.
67     *
68     * @return whether there are any saved credentials
69     * @see #getHttpAuthUsernamePassword
70     * @see #setHttpAuthUsernamePassword
71     * @see #clearHttpAuthUsernamePassword
72     */
73    public abstract boolean hasHttpAuthUsernamePassword();
74
75    /**
76     * Clears any saved credentials for HTTP authentication. This method only clears the username
77     * and password stored in WebViewDatabase instance. The username and password are not read from
78     * the {@link WebViewDatabase} during {@link WebViewClient#onReceivedHttpAuthRequest}. It is up
79     * to the app to do this or not.
80     * <p>
81     * The username and password used for http authentication might be cached in the network stack
82     * itself, and are not cleared when this method is called.  WebView does not provide a special
83     * mechanism to clear HTTP authentication for implementing client logout. The client logout
84     * mechanism should be implemented by the Web site designer (such as server sending a HTTP 401
85     * for invalidating credentials).
86     *
87     * @see #getHttpAuthUsernamePassword
88     * @see #setHttpAuthUsernamePassword
89     * @see #hasHttpAuthUsernamePassword
90     */
91    public abstract void clearHttpAuthUsernamePassword();
92
93    /**
94     * Stores HTTP authentication credentials for a given host and realm to the {@link WebViewDatabase}
95     * instance.
96     * <p>
97     * To use HTTP authentication, the embedder application has to implement
98     * {@link WebViewClient#onReceivedHttpAuthRequest}, and call {@link HttpAuthHandler#proceed}
99     * with the correct username and password.
100     * <p>
101     * The embedder app can get the username and password any way it chooses, and does not have to
102     * use {@link WebViewDatabase}.
103     * <p>
104     * Notes:
105     * <li>
106     * {@link WebViewDatabase} is provided only as a convenience to store and retrieve http
107     * authentication credentials. WebView does not read from it during HTTP authentication.
108     * </li>
109     * <li>
110     * WebView does not provide a special mechanism to clear HTTP authentication credentials for
111     * implementing client logout. The client logout mechanism should be implemented by the Web site
112     * designer (such as server sending a HTTP 401 for invalidating credentials).
113     * </li>
114     *
115     * @param host the host to which the credentials apply
116     * @param realm the realm to which the credentials apply
117     * @param username the username
118     * @param password the password
119     * @see #getHttpAuthUsernamePassword
120     * @see #hasHttpAuthUsernamePassword
121     * @see #clearHttpAuthUsernamePassword
122     */
123    public abstract void setHttpAuthUsernamePassword(String host, String realm,
124            String username, String password);
125
126   /**
127     * Retrieves HTTP authentication credentials for a given host and realm from the {@link
128     * WebViewDatabase} instance.
129     *
130     * @param host the host to which the credentials apply
131     * @param realm the realm to which the credentials apply
132     * @return the credentials as a String array, if found. The first element
133     *         is the username and the second element is the password. {@code null} if
134     *         no credentials are found.
135     * @see #setHttpAuthUsernamePassword
136     * @see #hasHttpAuthUsernamePassword
137     * @see #clearHttpAuthUsernamePassword
138     */
139    @Nullable
140    public abstract String[] getHttpAuthUsernamePassword(String host, String realm);
141
142    /**
143     * Gets whether there is any saved data for web forms.
144     *
145     * @return whether there is any saved data for web forms
146     * @see #clearFormData
147     */
148    @Deprecated
149    public abstract boolean hasFormData();
150
151    /**
152     * Clears any saved data for web forms.
153     *
154     * @see #hasFormData
155     */
156    @Deprecated
157    public abstract void clearFormData();
158}
159