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 * @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 */ updateQuota(long newQuota)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 */ Origin(String origin, long quota, long usage)68 protected Origin(String origin, long quota, long usage) { 69 mOrigin = origin; 70 mQuota = quota; 71 mUsage = usage; 72 } 73 74 /** @hide */ Origin(String origin, long quota)75 protected Origin(String origin, long quota) { 76 mOrigin = origin; 77 mQuota = quota; 78 } 79 80 /** @hide */ Origin(String origin)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. getOrigin()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 */ getQuota()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 */ getUsage()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 */ getOrigins(ValueCallback<Map> callback)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 */ getUsageForOrigin(String origin, ValueCallback<Long> callback)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 */ getQuotaForOrigin(String origin, ValueCallback<Long> callback)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 setQuotaForOrigin(String origin, long quota)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 */ deleteOrigin(String origin)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 */ deleteAllData()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 */ getInstance()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 */ WebStorage()213 public WebStorage() {} 214 } 215