Debian Codegraph @

closure-library/closure/goog/storage/mechanism/ieuserdata.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 Provides data persistence using IE userData mechanism.
17 * UserData uses proprietary Element.addBehavior(), Element.load(),
18 * Element.save(), and Element.XMLDocument() methods, see:
19 * http://msdn.microsoft.com/en-us/library/ms531424(v=vs.85).aspx.
20 *
21 */
22
23 goog.provide('goog.storage.mechanism.IEUserData');
24
25 goog.require('goog.asserts');
26 goog.require('goog.iter.Iterator');
27 goog.require('goog.iter.StopIteration');
28 goog.require('goog.storage.mechanism.ErrorCode');
29 goog.require('goog.storage.mechanism.IterableMechanism');
30 goog.require('goog.structs.Map');
31 goog.require('goog.userAgent');
32
33
34
35 /**
36 * Provides a storage mechanism using IE userData.
37 *
38 * @param {string} storageKey The key (store name) to store the data under.
39 * @param {string=} opt_storageNodeId The ID of the associated HTML element,
40 * one will be created if not provided.
41 * @constructor
42 * @extends {goog.storage.mechanism.IterableMechanism}
43 * @final
44 */
45 goog.storage.mechanism.IEUserData = function(storageKey, opt_storageNodeId) {
46 /**
47 * The key to store the data under.
48 *
49 * @private {?string}
50 */
51 this.storageKey_ = storageKey;
52
53 /**
54 * The document element used for storing data.
55 *
56 * @private {Element}
57 */
58 this.storageNode_ = null;
59
60 goog.storage.mechanism.IEUserData.base(this, 'constructor');
61
62 // Tested on IE6, IE7 and IE8. It seems that IE9 introduces some security
63 // features which make persistent (loaded) node attributes invisible from
64 // JavaScript.
65 if (goog.userAgent.IE && !goog.userAgent.isDocumentModeOrHigher(9)) {
66 if (!goog.storage.mechanism.IEUserData.storageMap_) {
67 goog.storage.mechanism.IEUserData.storageMap_ = new goog.structs.Map();
68 }
69 this.storageNode_ = /** @type {Element} */ (
70 goog.storage.mechanism.IEUserData.storageMap_.get(storageKey));
71 if (!this.storageNode_) {
72 if (opt_storageNodeId) {
73 this.storageNode_ = document.getElementById(opt_storageNodeId);
74 } else {
75 this.storageNode_ = document.createElement('userdata');
76 // This is a special IE-only method letting us persist data.
77 this.storageNode_['addBehavior']('#default#userData');
78 document.body.appendChild(this.storageNode_);
79 }
80 goog.storage.mechanism.IEUserData.storageMap_.set(
81 storageKey, this.storageNode_);
82 }
83
84
85 try {
86 // Availability check.
87 this.loadNode_();
88 } catch (e) {
89 this.storageNode_ = null;
90 }
91 }
92 };
93 goog.inherits(
94 goog.storage.mechanism.IEUserData,
95 goog.storage.mechanism.IterableMechanism);
96
97
98 /**
99 * Encoding map for characters which are not encoded by encodeURIComponent().
100 * See encodeKey_ documentation for encoding details.
101 *
102 * @type {!Object}
103 * @const
104 */
105 goog.storage.mechanism.IEUserData.ENCODE_MAP = {
106 '.': '.2E',
107 '!': '.21',
108 '~': '.7E',
109 '*': '.2A',
110 '\'': '.27',
111 '(': '.28',
112 ')': '.29',
113 '%': '.'
114 };
115
116
117 /**
118 * Global storageKey to storageNode map, so we save on reloading the storage.
119 *
120 * @type {goog.structs.Map}
121 * @private
122 */
123 goog.storage.mechanism.IEUserData.storageMap_ = null;
124
125
126 /**
127 * Encodes anything other than [-a-zA-Z0-9_] using a dot followed by hex,
128 * and prefixes with underscore to form a valid and safe HTML attribute name.
129 *
130 * We use URI encoding to do the initial heavy lifting, then escape the
131 * remaining characters that we can't use. Since a valid attribute name can't
132 * contain the percent sign (%), we use a dot (.) as an escape character.
133 *
134 * @param {string} key The key to be encoded.
135 * @return {string} The encoded key.
136 * @private
137 */
138 goog.storage.mechanism.IEUserData.encodeKey_ = function(key) {
139 // encodeURIComponent leaves - _ . ! ~ * ' ( ) unencoded.
140 return '_' + encodeURIComponent(key).replace(/[.!~*'()%]/g, function(c) {
141 return goog.storage.mechanism.IEUserData.ENCODE_MAP[c];
142 });
143 };
144
145
146 /**
147 * Decodes a dot-encoded and character-prefixed key.
148 * See encodeKey_ documentation for encoding details.
149 *
150 * @param {string} key The key to be decoded.
151 * @return {string} The decoded key.
152 * @private
153 */
154 goog.storage.mechanism.IEUserData.decodeKey_ = function(key) {
155 return decodeURIComponent(key.replace(/\./g, '%')).substr(1);
156 };
157
158
159 /**
160 * Determines whether or not the mechanism is available.
161 *
162 * @return {boolean} True if the mechanism is available.
163 */
164 goog.storage.mechanism.IEUserData.prototype.isAvailable = function() {
165 return !!this.storageNode_;
166 };
167
168
169 /** @override */
170 goog.storage.mechanism.IEUserData.prototype.set = function(key, value) {
171 this.storageNode_.setAttribute(
172 goog.storage.mechanism.IEUserData.encodeKey_(key), value);
173 this.saveNode_();
174 };
175
176
177 /** @override */
178 goog.storage.mechanism.IEUserData.prototype.get = function(key) {
179 // According to Microsoft, values can be strings, numbers or booleans. Since
180 // we only save strings, any other type is a storage error. If we returned
181 // nulls for such keys, i.e., treated them as non-existent, this would lead
182 // to a paradox where a key exists, but it does not when it is retrieved.
183 // http://msdn.microsoft.com/en-us/library/ms531348(v=vs.85).aspx
184 var value = this.storageNode_.getAttribute(
185 goog.storage.mechanism.IEUserData.encodeKey_(key));
186 if (!goog.isString(value) && !goog.isNull(value)) {
187 throw goog.storage.mechanism.ErrorCode.INVALID_VALUE;
188 }
189 return value;
190 };
191
192
193 /** @override */
194 goog.storage.mechanism.IEUserData.prototype.remove = function(key) {
195 this.storageNode_.removeAttribute(
196 goog.storage.mechanism.IEUserData.encodeKey_(key));
197 this.saveNode_();
198 };
199
200
201 /** @override */
202 goog.storage.mechanism.IEUserData.prototype.getCount = function() {
203 return this.getNode_().attributes.length;
204 };
205
206
207 /** @override */
208 goog.storage.mechanism.IEUserData.prototype.__iterator__ = function(opt_keys) {
209 var i = 0;
210 var attributes = this.getNode_().attributes;
211 var newIter = new goog.iter.Iterator();
212 newIter.next = function() {
213 if (i >= attributes.length) {
214 throw goog.iter.StopIteration;
215 }
216 var item = goog.asserts.assert(attributes[i++]);
217 if (opt_keys) {
218 return goog.storage.mechanism.IEUserData.decodeKey_(item.nodeName);
219 }
220 var value = item.nodeValue;
221 // The value must exist and be a string, otherwise it is a storage error.
222 if (!goog.isString(value)) {
223 throw goog.storage.mechanism.ErrorCode.INVALID_VALUE;
224 }
225 return value;
226 };
227 return newIter;
228 };
229
230
231 /** @override */
232 goog.storage.mechanism.IEUserData.prototype.clear = function() {
233 var node = this.getNode_();
234 for (var left = node.attributes.length; left > 0; left--) {
235 node.removeAttribute(node.attributes[left - 1].nodeName);
236 }
237 this.saveNode_();
238 };
239
240
241 /**
242 * Loads the underlying storage node to the state we saved it to before.
243 *
244 * @private
245 */
246 goog.storage.mechanism.IEUserData.prototype.loadNode_ = function() {
247 // This is a special IE-only method on Elements letting us persist data.
248 this.storageNode_['load'](this.storageKey_);
249 };
250
251
252 /**
253 * Saves the underlying storage node.
254 *
255 * @private
256 */
257 goog.storage.mechanism.IEUserData.prototype.saveNode_ = function() {
258
259 try {
260 // This is a special IE-only method on Elements letting us persist data.
261 // Do not try to assign this.storageNode_['save'] to a variable, it does
262 // not work. May throw an exception when the quota is exceeded.
263 this.storageNode_['save'](this.storageKey_);
264 } catch (e) {
265 throw goog.storage.mechanism.ErrorCode.QUOTA_EXCEEDED;
266 }
267 };
268
269
270 /**
271 * Returns the storage node.
272 *
273 * @return {!Element} Storage DOM Element.
274 * @private
275 */
276 goog.storage.mechanism.IEUserData.prototype.getNode_ = function() {
277 // This is a special IE-only property letting us browse persistent data.
278 var doc = /** @type {Document} */ (this.storageNode_['XMLDocument']);
279 return doc.documentElement;
280 };