Debian Codegraph @

closure-library/closure/goog/storage/mechanism/html5webstorage.js

raw
1 // Copyright 2011 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Base class that implements functionality common
17 * across both session and local web storage mechanisms.
18 *
19 */
20
21 goog.provide('goog.storage.mechanism.HTML5WebStorage');
22
23 goog.require('goog.asserts');
24 goog.require('goog.iter.Iterator');
25 goog.require('goog.iter.StopIteration');
26 goog.require('goog.storage.mechanism.ErrorCode');
27 goog.require('goog.storage.mechanism.IterableMechanism');
28
29
30
31 /**
32 * Provides a storage mechanism that uses HTML5 Web storage.
33 *
34 * @param {Storage} storage The Web storage object.
35 * @constructor
36 * @struct
37 * @extends {goog.storage.mechanism.IterableMechanism}
38 */
39 goog.storage.mechanism.HTML5WebStorage = function(storage) {
40 goog.storage.mechanism.HTML5WebStorage.base(this, 'constructor');
41
42 /**
43 * The web storage object (window.localStorage or window.sessionStorage).
44 * @private {Storage}
45 */
46 this.storage_ = storage;
47 };
48 goog.inherits(
49 goog.storage.mechanism.HTML5WebStorage,
50 goog.storage.mechanism.IterableMechanism);
51
52
53 /**
54 * The key used to check if the storage instance is available.
55 * @private {string}
56 * @const
57 */
58 goog.storage.mechanism.HTML5WebStorage.STORAGE_AVAILABLE_KEY_ = '__sak';
59
60
61 /**
62 * Determines whether or not the mechanism is available.
63 * It works only if the provided web storage object exists and is enabled.
64 *
65 * @return {boolean} True if the mechanism is available.
66 */
67 goog.storage.mechanism.HTML5WebStorage.prototype.isAvailable = function() {
68 if (!this.storage_) {
69 return false;
70 }
71
72 try {
73 // setItem will throw an exception if we cannot access WebStorage (e.g.,
74 // Safari in private mode).
75 this.storage_.setItem(
76 goog.storage.mechanism.HTML5WebStorage.STORAGE_AVAILABLE_KEY_, '1');
77 this.storage_.removeItem(
78 goog.storage.mechanism.HTML5WebStorage.STORAGE_AVAILABLE_KEY_);
79 return true;
80 } catch (e) {
81 return false;
82 }
83 };
84
85
86 /** @override */
87 goog.storage.mechanism.HTML5WebStorage.prototype.set = function(key, value) {
88
89 try {
90 // May throw an exception if storage quota is exceeded.
91 this.storage_.setItem(key, value);
92 } catch (e) {
93 // In Safari Private mode, conforming to the W3C spec, invoking
94 // Storage.prototype.setItem will allways throw a QUOTA_EXCEEDED_ERR
95 // exception. Since it's impossible to verify if we're in private browsing
96 // mode, we throw a different exception if the storage is empty.
97 if (this.storage_.length == 0) {
98 throw goog.storage.mechanism.ErrorCode.STORAGE_DISABLED;
99 } else {
100 throw goog.storage.mechanism.ErrorCode.QUOTA_EXCEEDED;
101 }
102 }
103 };
104
105
106 /** @override */
107 goog.storage.mechanism.HTML5WebStorage.prototype.get = function(key) {
108 // According to W3C specs, values can be of any type. Since we only save
109 // strings, any other type is a storage error. If we returned nulls for
110 // such keys, i.e., treated them as non-existent, this would lead to a
111 // paradox where a key exists, but it does not when it is retrieved.
112 // http://www.w3.org/TR/2009/WD-webstorage-20091029/#the-storage-interface
113 var value = this.storage_.getItem(key);
114 if (!goog.isString(value) && !goog.isNull(value)) {
115 throw goog.storage.mechanism.ErrorCode.INVALID_VALUE;
116 }
117 return value;
118 };
119
120
121 /** @override */
122 goog.storage.mechanism.HTML5WebStorage.prototype.remove = function(key) {
123 this.storage_.removeItem(key);
124 };
125
126
127 /** @override */
128 goog.storage.mechanism.HTML5WebStorage.prototype.getCount = function() {
129 return this.storage_.length;
130 };
131
132
133 /** @override */
134 goog.storage.mechanism.HTML5WebStorage.prototype.__iterator__ = function(
135 opt_keys) {
136 var i = 0;
137 var storage = this.storage_;
138 var newIter = new goog.iter.Iterator();
139 newIter.next = function() {
140 if (i >= storage.length) {
141 throw goog.iter.StopIteration;
142 }
143 var key = goog.asserts.assertString(storage.key(i++));
144 if (opt_keys) {
145 return key;
146 }
147 var value = storage.getItem(key);
148 // The value must exist and be a string, otherwise it is a storage error.
149 if (!goog.isString(value)) {
150 throw goog.storage.mechanism.ErrorCode.INVALID_VALUE;
151 }
152 return value;
153 };
154 return newIter;
155 };
156
157
158 /** @override */
159 goog.storage.mechanism.HTML5WebStorage.prototype.clear = function() {
160 this.storage_.clear();
161 };
162
163
164 /**
165 * Gets the key for a given key index. If an index outside of
166 * [0..this.getCount()) is specified, this function returns null.
167 * @param {number} index A key index.
168 * @return {?string} A storage key, or null if the specified index is out of
169 * range.
170 */
171 goog.storage.mechanism.HTML5WebStorage.prototype.key = function(index) {
172 return this.storage_.key(index);
173 };