1
// Licensed to the Software Freedom Conservancy (SFC) under one
2
// or more contributor license agreements.  See the NOTICE file
3
// distributed with this work for additional information
4
// regarding copyright ownership.  The SFC licenses this file
5
// to you under the Apache License, Version 2.0 (the
6
// "License"); you may not use this file except in compliance
7
// with the License.  You may obtain a copy of the License at
8
//
9
//   http://www.apache.org/licenses/LICENSE-2.0
10
//
11
// Unless required by applicable law or agreed to in writing,
12
// software distributed under the License is distributed on an
13
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14
// KIND, either express or implied.  See the License for the
15
// specific language governing permissions and limitations
16
// under the License.
17

18
/**
19
 * @fileoverview Atoms for accessing HTML5 web storage maps (localStorage,
20
 * sessionStorage). These storage objects store each item as a key-value
21
 * mapping pair.
22
 *
23
 */
24

25
goog.provide('bot.storage');
26
goog.provide('bot.storage.Storage');
27

28
goog.require('bot');
29
goog.require('bot.Error');
30
goog.require('bot.ErrorCode');
31
goog.require('bot.html5');
32

33

34
/**
35
 * A factory method to create a wrapper to access the HTML5 localStorage
36
 * object.
37
 * Note: We are not using Closure from goog.storage,
38
 * Closure uses "window" object directly, which may not always be
39
 * defined (for example in firefox extensions).
40
 * We use bot.window() from bot.js instead to keep track of the window or frame
41
 * is currently being used for command execution. The implementation is
42
 * otherwise similar to the implementation in the Closure library
43
 * (goog.storage.mechanism.HTML5LocalStorage).
44
 *
45
 * @param {Window=} opt_window The window whose storage to access;
46
 *     defaults to the main window.
47
 * @return {!bot.storage.Storage} The wrapper Storage object.
48
 */
49
bot.storage.getLocalStorage = function(opt_window) {
50
  var win = opt_window || bot.getWindow();
51

52
  if (!bot.html5.isSupported(bot.html5.API.LOCAL_STORAGE, win)) {
53
    throw new bot.Error(bot.ErrorCode.UNKNOWN_ERROR, 'Local storage undefined');
54
  }
55
  var storageMap = win.localStorage;
56
  return new bot.storage.Storage(storageMap);
57
};
58

59

60
/**
61
 * A factory method to create a wrapper to access the HTML5 sessionStorage
62
 * object.
63
 *
64
 * @param {Window=} opt_window The window whose storage to access;
65
 *     defaults to the main window.
66
 * @return {!bot.storage.Storage} The wrapper Storage object.
67
 */
68
bot.storage.getSessionStorage = function(opt_window) {
69
  var win = opt_window || bot.getWindow();
70

71
  if (bot.html5.isSupported(bot.html5.API.SESSION_STORAGE, win)) {
72
    var storageMap = win.sessionStorage;
73
    return new bot.storage.Storage(storageMap);
74
  }
75
  throw new bot.Error(bot.ErrorCode.UNKNOWN_ERROR,
76
      'Session storage undefined');
77
};
78

79

80

81
/**
82
 * Provides a wrapper object to the HTML5 web storage object.
83
 * @constructor
84
 *
85
 * @param {Storage} storageMap HTML5 storage object e.g. localStorage,
86
 *     sessionStorage.
87
 */
88
bot.storage.Storage = function(storageMap) {
89
  /**
90
   * Member variable to access the assigned HTML5 storage object.
91
   * @private {Storage}
92
   * @const
93
   */
94
  this.storageMap_ = storageMap;
95
};
96

97

98
/**
99
 * Sets the value item of a key/value pair in the Storage object.
100
 * If the value given is null, the string 'null' will be inserted
101
 * instead.
102
 *
103
 * @param {string} key The key of the item.
104
 * @param {*} value The value of the item.
105
 */
106
bot.storage.Storage.prototype.setItem = function(key, value) {
107
  try {
108
    // Note: Ideally, browsers should set a null value. But the browsers
109
    // report arbitrarily. Firefox returns <null>, while Chrome reports
110
    // the string "null". We are setting the value to the string "null".
111
    this.storageMap_.setItem(key, value + '');
112
  } catch (e) {
113
    throw new bot.Error(bot.ErrorCode.UNKNOWN_ERROR, e.message);
114
  }
115
};
116

117

118
/**
119
 * Returns the value item of a key in the Storage object.
120
 *
121
 * @param {string} key The key of the returned value.
122
 * @return {?string} The mapped value if present in the storage object,
123
 *     otherwise null. If a null value  was inserted for a given
124
 *     key, then the string 'null' is returned.
125
 */
126
bot.storage.Storage.prototype.getItem = function(key) {
127
  var value = this.storageMap_.getItem(key);
128
  return /** @type {?string} */ (value);
129
};
130

131

132
/**
133
 * Returns an array of keys of all keys of the Storage object.
134
 *
135
 * @return {!Array.<string>} The array of stored keys..
136
 */
137
bot.storage.Storage.prototype.keySet = function() {
138
  var keys = [];
139
  var length = this.size();
140
  for (var i = 0; i < length; i++) {
141
    keys[i] = this.storageMap_.key(i);
142
  }
143
  return keys;
144
};
145

146

147
/**
148
 * Removes an item with a given key.
149
 *
150
 * @param {string} key The key item of the key/value pair.
151
 * @return {?string} The removed value if present, otherwise null.
152
 */
153
bot.storage.Storage.prototype.removeItem = function(key) {
154
  var value = this.getItem(key);
155
  this.storageMap_.removeItem(key);
156
  return value;
157
};
158

159

160
/**
161
 * Removes all items.
162
 */
163
bot.storage.Storage.prototype.clear = function() {
164
  this.storageMap_.clear();
165
};
166

167

168
/**
169
 * Returns the number of items in the Storage object.
170
 *
171
 * @return {number} The number of the key/value pairs.
172
 */
173
bot.storage.Storage.prototype.size = function() {
174
  return this.storageMap_.length;
175
};
176

177

178
/**
179
 * Returns the key item of the key/value pairs in the Storage object
180
 * of a given index.
181
 *
182
 * @param {number} index The index of the key/value pair list.
183
 * @return {?string} The key item of a given index.
184
 */
185
bot.storage.Storage.prototype.key = function(index) {
186
  return this.storageMap_.key(index);
187
};
188

189

190
/**
191
 * Returns HTML5 storage object of the wrapper Storage object
192
 *
193
 * @return {Storage} The storageMap attribute.
194
 */
195
bot.storage.Storage.prototype.getStorageMap = function() {
196
  return this.storageMap_;
197
};
198

199