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