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