17df1985e86635af006be3dfa65987d60e290b5deBen Murdoch/*
27df1985e86635af006be3dfa65987d60e290b5deBen Murdoch * Copyright (C) 2009 The Android Open Source Project
37df1985e86635af006be3dfa65987d60e290b5deBen Murdoch *
47df1985e86635af006be3dfa65987d60e290b5deBen Murdoch * Licensed under the Apache License, Version 2.0 (the "License");
57df1985e86635af006be3dfa65987d60e290b5deBen Murdoch * you may not use this file except in compliance with the License.
67df1985e86635af006be3dfa65987d60e290b5deBen Murdoch * You may obtain a copy of the License at
77df1985e86635af006be3dfa65987d60e290b5deBen Murdoch *
87df1985e86635af006be3dfa65987d60e290b5deBen Murdoch *      http://www.apache.org/licenses/LICENSE-2.0
97df1985e86635af006be3dfa65987d60e290b5deBen Murdoch *
107df1985e86635af006be3dfa65987d60e290b5deBen Murdoch * Unless required by applicable law or agreed to in writing, software
117df1985e86635af006be3dfa65987d60e290b5deBen Murdoch * distributed under the License is distributed on an "AS IS" BASIS,
127df1985e86635af006be3dfa65987d60e290b5deBen Murdoch * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
137df1985e86635af006be3dfa65987d60e290b5deBen Murdoch * See the License for the specific language governing permissions and
147df1985e86635af006be3dfa65987d60e290b5deBen Murdoch * limitations under the License.
157df1985e86635af006be3dfa65987d60e290b5deBen Murdoch */
167df1985e86635af006be3dfa65987d60e290b5deBen Murdoch
177df1985e86635af006be3dfa65987d60e290b5deBen Murdochpackage android.webkit;
187df1985e86635af006be3dfa65987d60e290b5deBen Murdoch
1936196b6d4a413b65c9f1f82112ae34a46dcedfc6Jonathan Dixonimport java.util.Map;
2011e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
217df1985e86635af006be3dfa65987d60e290b5deBen Murdoch/**
22285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block * This class is used to manage the JavaScript storage APIs provided by the
23285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block * {@link WebView}. It manages the Application Cache API, the Web SQL Database
24285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block * API and the HTML5 Web Storage API.
25285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block *
26b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun * The Application Cache API provides a mechanism to create and maintain an
27b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun * application cache to power offline Web applications. Use of the Application
28b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun * Cache API can be attributed to an origin {@link WebStorage.Origin}, however
29b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun * it is not possible to set per-origin quotas. Note that there can be only
30b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun * one application cache per application.
31b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun *
32b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun * The Web SQL Database API provides storage which is private to a given origin.
33b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun * Similar to the Application Cache, use of the Web SQL Database can be attributed
34b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun * to an origin. It is also possible to set per-origin quotas.
357df1985e86635af006be3dfa65987d60e290b5deBen Murdoch */
36939e5040b51539be561db1d18dec18196f201f5cJonathan Dixonpublic class WebStorage {
377df1985e86635af006be3dfa65987d60e290b5deBen Murdoch
387df1985e86635af006be3dfa65987d60e290b5deBen Murdoch    /**
39285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * Encapsulates a callback function which is used to provide a new quota
40b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun     * for a JavaScript storage API.
41b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun     * See
42285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * {@link WebChromeClient#onExceededDatabaseQuota} and
43285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * {@link WebChromeClient#onReachedMaxAppCacheSize}.
445545d083d35620a625b65fafe97199660d85f059Jonathan Dixon     * @deprecated This class is obsolete and no longer used.
457df1985e86635af006be3dfa65987d60e290b5deBen Murdoch     */
465545d083d35620a625b65fafe97199660d85f059Jonathan Dixon    @Deprecated
477df1985e86635af006be3dfa65987d60e290b5deBen Murdoch    public interface QuotaUpdater {
48285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block        /**
494e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         * Provides a new quota, specified in bytes.
504e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         *
514e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         * @param newQuota the new quota, in bytes
52285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block         */
537df1985e86635af006be3dfa65987d60e290b5deBen Murdoch        public void updateQuota(long newQuota);
547df1985e86635af006be3dfa65987d60e290b5deBen Murdoch    };
5511e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
569b2a59bdd27cfa45c7bb3b58eb705b35589b7050John Reck    /**
57285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * This class encapsulates information about the amount of storage
58285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * currently used by an origin for the JavaScript storage APIs.
59b632adfaf445ff6f0c07bfc54671d204ad0e5a67Selim Gurun     * An origin comprises the host, scheme and port of a URI.
60285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * See {@link WebStorage} for details.
619b2a59bdd27cfa45c7bb3b58eb705b35589b7050John Reck     */
6287745ce21fe3f65b8cf7a92372c24227821318d3John Reck    public static class Origin {
6387745ce21fe3f65b8cf7a92372c24227821318d3John Reck        private String mOrigin = null;
6487745ce21fe3f65b8cf7a92372c24227821318d3John Reck        private long mQuota = 0;
6587745ce21fe3f65b8cf7a92372c24227821318d3John Reck        private long mUsage = 0;
666c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard
67d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        /** @hide */
68d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        protected Origin(String origin, long quota, long usage) {
696c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard            mOrigin = origin;
706c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard            mQuota = quota;
716c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard            mUsage = usage;
726c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard        }
7311e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
74d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        /** @hide */
75d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        protected Origin(String origin, long quota) {
7611e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard            mOrigin = origin;
7711e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard            mQuota = quota;
7811e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard        }
7911e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
80d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        /** @hide */
81d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        protected Origin(String origin) {
8211e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard            mOrigin = origin;
8311e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard        }
8411e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
859b2a59bdd27cfa45c7bb3b58eb705b35589b7050John Reck        /**
864e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         * Gets the string representation of this origin.
874e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         *
884e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         * @return the string representation of this origin
899b2a59bdd27cfa45c7bb3b58eb705b35589b7050John Reck         */
90285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block        // An origin string is created using WebCore::SecurityOrigin::toString().
91285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block        // Note that WebCore::SecurityOrigin uses 0 (which is not printed) for
92285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block        // the port if the port is the default for the protocol. Eg
93285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block        // http://www.google.com and http://www.google.com:80 both record a port
94285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block        // of 0 and hence toString() == 'http://www.google.com' for both.
9511e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard        public String getOrigin() {
9611e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard            return mOrigin;
9711e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard        }
9811e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
999b2a59bdd27cfa45c7bb3b58eb705b35589b7050John Reck        /**
1004e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         * Gets the quota for this origin, for the Web SQL Database API, in
101285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block         * bytes. If this origin does not use the Web SQL Database API, this
102285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block         * quota will be set to zero.
1034e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         *
1044e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         * @return the quota, in bytes
1059b2a59bdd27cfa45c7bb3b58eb705b35589b7050John Reck         */
10611e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard        public long getQuota() {
10711e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard            return mQuota;
10811e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard        }
1096c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard
1109b2a59bdd27cfa45c7bb3b58eb705b35589b7050John Reck        /**
1114e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         * Gets the total amount of storage currently being used by this origin,
112285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block         * for all JavaScript storage APIs, in bytes.
1134e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         *
1144e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block         * @return the total amount of storage, in bytes
1159b2a59bdd27cfa45c7bb3b58eb705b35589b7050John Reck         */
1166c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard        public long getUsage() {
1176c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard            return mUsage;
1186c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard        }
1196c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard    }
1206c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard
1216c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard    /*
1226c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard     * When calling getOrigins(), getUsageForOrigin() and getQuotaForOrigin(),
123285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * we need to get the values from WebCore, but we cannot block while doing so
124285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * as we used to do, as this could result in a full deadlock (other WebCore
1256c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard     * messages received while we are still blocked here, see http://b/2127737).
1266c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard     *
1276c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard     * We have to do everything asynchronously, by providing a callback function.
128285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * We post a message on the WebCore thread (mHandler) that will get the result
129285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * from WebCore, and we post it back on the UI thread (using mUIHandler).
1306c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard     * We can then use the callback function to return the value.
1316c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard     */
1326c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard
13311e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    /**
1344e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block     * Gets the origins currently using either the Application Cache or Web SQL
135285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * Database APIs. This method operates asynchronously, with the result
136285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * being provided via a {@link ValueCallback}. The origins are provided as
137285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * a map, of type {@code Map<String, WebStorage.Origin>}, from the string
138285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * representation of the origin to a {@link WebStorage.Origin} object.
13911e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard     */
1406c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard    public void getOrigins(ValueCallback<Map> callback) {
141d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        // Must be a no-op for backward compatibility: see the hidden constructor for reason.
14211e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    }
14311e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
14411e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    /**
1454e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block     * Gets the amount of storage currently being used by both the Application
146285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * Cache and Web SQL Database APIs by the given origin. The amount is given
147285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * in bytes and the origin is specified using its string representation.
148285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * This method operates asynchronously, with the result being provided via
149285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * a {@link ValueCallback}.
15011e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard     */
1516c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard    public void getUsageForOrigin(String origin, ValueCallback<Long> callback) {
152d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        // Must be a no-op for backward compatibility: see the hidden constructor for reason.
15311e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    }
15411e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
15511e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    /**
1564e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block     * Gets the storage quota for the Web SQL Database API for the given origin.
157285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * The quota is given in bytes and the origin is specified using its string
158285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * representation. This method operates asynchronously, with the result
159285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * being provided via a {@link ValueCallback}. Note that a quota is not
160285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * enforced on a per-origin basis for the Application Cache API.
16111e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard     */
1626c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard    public void getQuotaForOrigin(String origin, ValueCallback<Long> callback) {
163d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        // Must be a no-op for backward compatibility: see the hidden constructor for reason.
16411e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    }
16511e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
16611e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    /**
1674e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block     * Sets the storage quota for the Web SQL Database API for the given origin.
168285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * The quota is specified in bytes and the origin is specified using its string
169285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * representation. Note that a quota is not enforced on a per-origin basis
170285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * for the Application Cache API.
171835b1fcc3193e0860ec33cca1c4cdff31f409473Jonathan Dixon     * @deprecated Controlling quota per-origin will not be supported in future.
17211e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard     */
173835b1fcc3193e0860ec33cca1c4cdff31f409473Jonathan Dixon    @Deprecated
17411e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    public void setQuotaForOrigin(String origin, long quota) {
175d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        // Must be a no-op for backward compatibility: see the hidden constructor for reason.
17611e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    }
17711e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
17811e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    /**
1794e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block     * Clears the storage currently being used by both the Application Cache and
180285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * Web SQL Database APIs by the given origin. The origin is specified using
181285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * its string representation.
18211e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard     */
18311e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    public void deleteOrigin(String origin) {
184d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        // Must be a no-op for backward compatibility: see the hidden constructor for reason.
18511e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    }
18611e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
18711e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    /**
1884e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block     * Clears all storage currently being used by the JavaScript storage APIs.
189285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * This includes the Application Cache, Web SQL Database and the HTML5 Web
190285ddfc8abfcdd252c50477b34c13f8173f9f3f4Steve Block     * Storage APIs.
19111e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard     */
192af9c77edbddfcf87a4dc17b95db84bf741674a9aAndrei Popescu    public void deleteAllData() {
193d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon        // Must be a no-op for backward compatibility: see the hidden constructor for reason.
1946c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard    }
1956c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard
1966c24b4d10223cb522e6bdbf0e334f61e672f4366Nicolas Roard    /**
1974e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block     * Gets the singleton instance of this class.
1984e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block     *
1994e584df4cee8334bc371c04a67bcd0a32e2f9480Steve Block     * @return the singleton {@link WebStorage} instance
20011e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard     */
20111e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    public static WebStorage getInstance() {
202d3101b1d300f5942fdb7dfa323dc8830c4edc007Jonathan Dixon      return WebViewFactory.getProvider().getWebStorage();
20311e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard    }
20411e8fe5a7208c9cd6afc2a0373761ae506d7707fNicolas Roard
205a3dc86e637873be115e68be50bd1b281beff7994Jonathan Dixon    /**
206a3dc86e637873be115e68be50bd1b281beff7994Jonathan Dixon     * This class should not be instantiated directly, applications must only use
207a3dc86e637873be115e68be50bd1b281beff7994Jonathan Dixon     * {@link #getInstance()} to obtain the instance.
208a3dc86e637873be115e68be50bd1b281beff7994Jonathan Dixon     * Note this constructor was erroneously public and published in SDK levels prior to 16, but
209a3dc86e637873be115e68be50bd1b281beff7994Jonathan Dixon     * applications using it would receive a non-functional instance of this class (there was no
210a3dc86e637873be115e68be50bd1b281beff7994Jonathan Dixon     * way to call createHandler() and createUIHandler(), so it would not work).
211a3dc86e637873be115e68be50bd1b281beff7994Jonathan Dixon     * @hide
212a3dc86e637873be115e68be50bd1b281beff7994Jonathan Dixon     */
213a3dc86e637873be115e68be50bd1b281beff7994Jonathan Dixon    public WebStorage() {}
2147df1985e86635af006be3dfa65987d60e290b5deBen Murdoch}
215