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