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