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