1 /*
2  * Copyright (C) 2009 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 
17 package android.webkit;
18 
19 import android.annotation.SystemApi;
20 
21 import java.util.Map;
22 
23 /**
24  * This class is used to manage the JavaScript storage APIs provided by the
25  * {@link WebView}. It manages the Application Cache API, the Web SQL Database
26  * API and the HTML5 Web Storage API.
27  *
28  * The Application Cache API provides a mechanism to create and maintain an
29  * application cache to power offline Web applications. Use of the Application
30  * Cache API can be attributed to an origin {@link WebStorage.Origin}, however
31  * it is not possible to set per-origin quotas. Note that there can be only
32  * one application cache per application.
33  *
34  * The Web SQL Database API provides storage which is private to a given origin.
35  * Similar to the Application Cache, use of the Web SQL Database can be attributed
36  * to an origin. It is also possible to set per-origin quotas.
37  */
38 public class WebStorage {
39 
40     /**
41      * Encapsulates a callback function which is used to provide a new quota
42      * for a JavaScript storage API.
43      * See
44      * {@link WebChromeClient#onExceededDatabaseQuota} and
45      * {@link WebChromeClient#onReachedMaxAppCacheSize}.
46      * @deprecated This class is obsolete and no longer used.
47      */
48     @Deprecated
49     public interface QuotaUpdater {
50         /**
51          * Provides a new quota, specified in bytes.
52          *
53          * @param newQuota the new quota, in bytes
54          */
updateQuota(long newQuota)55         public void updateQuota(long newQuota);
56     };
57 
58     /**
59      * This class encapsulates information about the amount of storage
60      * currently used by an origin for the JavaScript storage APIs.
61      * An origin comprises the host, scheme and port of a URI.
62      * See {@link WebStorage} for details.
63      */
64     public static class Origin {
65         private String mOrigin = null;
66         private long mQuota = 0;
67         private long mUsage = 0;
68 
69         /** @hide */
70         @SystemApi
Origin(String origin, long quota, long usage)71         protected Origin(String origin, long quota, long usage) {
72             mOrigin = origin;
73             mQuota = quota;
74             mUsage = usage;
75         }
76 
77         /**
78          * Gets the string representation of this origin.
79          *
80          * @return the string representation of this origin
81          */
82         // An origin string is created using WebCore::SecurityOrigin::toString().
83         // Note that WebCore::SecurityOrigin uses 0 (which is not printed) for
84         // the port if the port is the default for the protocol. Eg
85         // http://www.google.com and http://www.google.com:80 both record a port
86         // of 0 and hence toString() == 'http://www.google.com' for both.
getOrigin()87         public String getOrigin() {
88             return mOrigin;
89         }
90 
91         /**
92          * Gets the quota for this origin, for the Web SQL Database API, in
93          * bytes. If this origin does not use the Web SQL Database API, this
94          * quota will be set to zero.
95          *
96          * @return the quota, in bytes
97          */
getQuota()98         public long getQuota() {
99             return mQuota;
100         }
101 
102         /**
103          * Gets the total amount of storage currently being used by this origin,
104          * for all JavaScript storage APIs, in bytes.
105          *
106          * @return the total amount of storage, in bytes
107          */
getUsage()108         public long getUsage() {
109             return mUsage;
110         }
111     }
112 
113     /*
114      * When calling getOrigins(), getUsageForOrigin() and getQuotaForOrigin(),
115      * we need to get the values from WebCore, but we cannot block while doing so
116      * as we used to do, as this could result in a full deadlock (other WebCore
117      * messages received while we are still blocked here, see http://b/2127737).
118      *
119      * We have to do everything asynchronously, by providing a callback function.
120      * We post a message on the WebCore thread (mHandler) that will get the result
121      * from WebCore, and we post it back on the UI thread (using mUIHandler).
122      * We can then use the callback function to return the value.
123      */
124 
125     /**
126      * Gets the origins currently using either the Application Cache or Web SQL
127      * Database APIs. This method operates asynchronously, with the result
128      * being provided via a {@link ValueCallback}. The origins are provided as
129      * a map, of type {@code Map<String, WebStorage.Origin>}, from the string
130      * representation of the origin to a {@link WebStorage.Origin} object.
131      */
getOrigins(ValueCallback<Map> callback)132     public void getOrigins(ValueCallback<Map> callback) {
133         // Must be a no-op for backward compatibility: see the hidden constructor for reason.
134     }
135 
136     /**
137      * Gets the amount of storage currently being used by both the Application
138      * Cache and Web SQL Database APIs by the given origin. The amount is given
139      * in bytes and the origin is specified using its string representation.
140      * This method operates asynchronously, with the result being provided via
141      * a {@link ValueCallback}.
142      */
getUsageForOrigin(String origin, ValueCallback<Long> callback)143     public void getUsageForOrigin(String origin, ValueCallback<Long> callback) {
144         // Must be a no-op for backward compatibility: see the hidden constructor for reason.
145     }
146 
147     /**
148      * Gets the storage quota for the Web SQL Database API for the given origin.
149      * The quota is given in bytes and the origin is specified using its string
150      * representation. This method operates asynchronously, with the result
151      * being provided via a {@link ValueCallback}. Note that a quota is not
152      * enforced on a per-origin basis for the Application Cache API.
153      */
getQuotaForOrigin(String origin, ValueCallback<Long> callback)154     public void getQuotaForOrigin(String origin, ValueCallback<Long> callback) {
155         // Must be a no-op for backward compatibility: see the hidden constructor for reason.
156     }
157 
158     /**
159      * Sets the storage quota for the Web SQL Database API for the given origin.
160      * The quota is specified in bytes and the origin is specified using its string
161      * representation. Note that a quota is not enforced on a per-origin basis
162      * for the Application Cache API.
163      * @deprecated Controlling quota per-origin will not be supported in future.
164      */
165     @Deprecated
setQuotaForOrigin(String origin, long quota)166     public void setQuotaForOrigin(String origin, long quota) {
167         // Must be a no-op for backward compatibility: see the hidden constructor for reason.
168     }
169 
170     /**
171      * Clears the storage currently being used by both the Application Cache and
172      * Web SQL Database APIs by the given origin. The origin is specified using
173      * its string representation.
174      */
deleteOrigin(String origin)175     public void deleteOrigin(String origin) {
176         // Must be a no-op for backward compatibility: see the hidden constructor for reason.
177     }
178 
179     /**
180      * Clears all storage currently being used by the JavaScript storage APIs.
181      * This includes the Application Cache, Web SQL Database and the HTML5 Web
182      * Storage APIs.
183      */
deleteAllData()184     public void deleteAllData() {
185         // Must be a no-op for backward compatibility: see the hidden constructor for reason.
186     }
187 
188     /**
189      * Gets the singleton instance of this class.
190      *
191      * @return the singleton {@link WebStorage} instance
192      */
getInstance()193     public static WebStorage getInstance() {
194       return WebViewFactory.getProvider().getWebStorage();
195     }
196 
197     /**
198      * This class should not be instantiated directly, applications must only use
199      * {@link #getInstance()} to obtain the instance.
200      * Note this constructor was erroneously public and published in SDK levels prior to 16, but
201      * applications using it would receive a non-functional instance of this class (there was no
202      * way to call createHandler() and createUIHandler(), so it would not work).
203      * @hide
204      */
205     @SystemApi
WebStorage()206     public WebStorage() {}
207 }
208