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