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