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 android.annotation.SystemApi;
20
21import 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 */
38public 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         */
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
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.
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         */
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         */
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     */
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     */
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     */
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
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     */
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     */
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     */
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
206    public WebStorage() {}
207}
208