1 /*
2 * Sybase Hybrid App version 2.3
3 *
4 * SUPStorage.js
5 * This file will not be regenerated, so it is possible to modify it, but it
6 * is not recommended.
7 *
8 * Copyright (c) 2012 Sybase Inc. All rights reserved.
9 */
10
11
12 /** @namespace */
13 hwc = (typeof hwc === "undefined" || !hwc) ? {} : hwc; // SUP 'namespace'
14
15
16 /**
17 * Access the storage functions, which allow you to specify a cache that stores results from online requests.
18 *
19 * These functions give you the ability to:
20 * Name the cached result sets
21 * Enumerate the cached result sets
22 * Read, delete, and modify cached contents individually for each cached result set
23 * Cached result sets must be stored as strings (before deserialization to an xmlWorkflowMessage structure).
24 */
25 (function(hwc, window, undefined) {
26
27 /**
28 * Creates a SUPStorage with the specified storeName. Provides encrypted storage of name value pairs. Results from online requests are one example.
29 * Strings stored in SUPStorage are encrypted and persisted to survive multiple invocations of the mobile workflow application.
30 * @constructor
31 * @param {String} store the store name
32 *
33 * @feature Storage
34 * @memberOf hwc
35 * @example
36 * var store1 = new hwc.SUPStorage("one");
37 */
38 hwc.SUPStorage = function(store) {
39 this.bForSharedStorage = false;
40 this.store = store ? store : "";
41 };
42
43 /**
44 * Gets the number of available keys in this object. The keys themselves may be
45 * retrieved using key().
46 * @feature Storage
47 * @example
48 * // Create the SUP Storage
49 * var store = new hwc.SUPStorage ("one");
50 * store.setItem ("foo", "bar"); // add an item.
51 * store.setItem ("foo1", "bar"); // add an item.
52 * store.setItem ("foo2", "bar"); // add an item.
53 * var result = store.length; // result = 3
54 * @public
55 * @memberOf hwc.SUPStorage
56 */
57 hwc.SUPStorage.prototype.length = function() {
58 var response;
59 hwc.traceEnteringMethod("hwc.SUPStorage.length");
60 try {
61 if (hwc.isWindowsMobile() || hwc.isIOS()) {
62 response = hwc.getDataFromContainer("workflowstorage", "&command=length&shared=" + this.bForSharedStorage +
63 "&store=" + encodeURIComponent(this.store));
64 return parseInt(response, 10);
65 }
66 else {
67 if (this.bForSharedStorage) {
68 return _SharedStorage.length(hwc.versionURLParam);
69 }
70 else {
71 return SUPStorage.length(this.store);
72 }
73 }
74 } finally {
75 hwc.traceLeavingMethod("hwc.SUPStorage.length");
76 }
77 };
78
79 /**
80 * Returns the key at the supplied index. Keys are guaranteed to remain
81 * at the same index until a modification is made.
82 *
83 *
84 * @param {Integer} index 0-based index to the key. Must be less than the value retrieved
85 * by .length.
86 * @return {String} The key, or null if the index is invalid.
87 * @feature Storage
88 * @public
89 * @memberOf hwc.SUPStorage
90 * @example
91 * // Create the SUP Storage
92 * var store = new hwc.SUPStorage ("one");
93 * store.setItem ("foo", "bar"); // add an item.
94 * var result = store.key (0); // will returns "foo".
95 */
96 hwc.SUPStorage.prototype.key = function(index) {
97 var key, isExist;
98 hwc.traceEnteringMethod("hwc.SUPStorage.key");
99 try {
100 if (null === index) {
101 return null;
102 }
103
104 if (hwc.isWindowsMobile() || hwc.isIOS()) {
105 key = hwc.getDataFromContainer("workflowstorage", "&command=key&shared=" + this.bForSharedStorage +
106 "&store=" + encodeURIComponent(this.store) + "&index=" + encodeURIComponent(index));
107
108 if (key === null || typeof key === 'undefined' || key === "") {
109 isExist = hwc.getDataFromContainer("workflowstorage", "&command=exist&shared=" + this.bForSharedStorage +
110 "&store=" + encodeURIComponent(this.store) + "&index=" + encodeURIComponent(index));
111
112 //WM returns empty string if an item does not exist or if the value is empty string
113 //call exist to distinguish this
114 if (isExist == "true") {
115 key = "";
116 }
117 else {
118 key = null;
119 }
120 }
121 }
122 else {
123 if (this.bForSharedStorage) {
124 key = _SharedStorage.key(index, hwc.versionURLParam);
125 }
126 else {
127 key = SUPStorage.key(this.store, index);
128 }
129 }
130
131 if (key === null || typeof key === 'undefined') {
132 return null;
133 } else {
134 return key + "";
135 }
136 } finally {
137 hwc.traceLeavingMethod("hwc.SUPStorage.key");
138 }
139 };
140
141 /**
142 * Helper method for parameter validation
143 * *PRIVATE*
144 * @private
145 * @param input: input value .
146 * @return if input is null, return empty string
147 */
148 function checkNull(input) {
149 if (null === input) {
150 input = "";
151 }
152 return input;
153 }
154
155 /**
156 * Retrieves the value associated with a specified key.
157 *
158 * @param {String} key String key corresponding to the requested value.
159 * @return {String} A String value corresponding to the key, or null if either the key
160 * is not known, or if the key exists but its value was set to null.
161 * @feature Storage
162 * @memberOf hwc.SUPStorage
163 * @example
164 * // Create the SUP Storage
165 * var store = new hwc.SUPStorage ("one");
166 * store.setItem ("foo", "bar"); // add an item.
167 * result = store.getItem ("foo"); // will returns "bar".
168 * result = store.getItem ("foo1"); // foo1 does not exists; will return null.
169 */
170 hwc.SUPStorage.prototype.getItem = function(key) {
171 var value, isExist;
172 key = key ? key : "";
173
174 hwc.traceEnteringMethod("hwc.SUPStorage.getItem");
175 try {
176 if (hwc.isWindowsMobile() || hwc.isIOS()) {
177 value = hwc.getDataFromContainer("workflowstorage", "&command=getItem&shared=" + this.bForSharedStorage +
178 "&store=" + encodeURIComponent(this.store) + "&key=" + encodeURIComponent(key));
179
180 if (value === null || typeof value === 'undefined' || value === "") {
181 isExist = hwc.getDataFromContainer("workflowstorage", "&command=exist&shared=" + this.bForSharedStorage +
182 "&store=" + encodeURIComponent(this.store) + "&key=" + encodeURIComponent(key));
183
184 //WM returns empty string if an item does not exist or if the value is empty string
185 //call exist to distinguish this
186 if (isExist == "true") {
187 value = "";
188 }
189 else {
190 value = null;
191 }
192 }
193 }
194 else {
195 if (this.bForSharedStorage) {
196 value = _SharedStorage.getItem(key, hwc.versionURLParam);
197 }
198 else {
199 value = SUPStorage.getItem(this.store, key);
200 }
201 }
202
203 if (value === null || typeof value === 'undefined') {
204 return null;
205 } else {
206 return value + "";
207 }
208 } finally {
209 hwc.traceLeavingMethod("hwc.SUPStorage.getItem");
210 }
211 };
212
213 /**
214 * A constant for the maximum length for a string being stored on BB7
215 * BB7 cannot handle strings with length longer than 524000
216 * This restriction applies to real devices as well as simulators.
217 */
218 hwc.SUPStorage.BB7_MAX_STRING_STORAGE_LENGTH = 524000;
219
220 /**
221 * Sets the value associated with a specified key. This replaces the key's
222 * previous value, if any.
223 *
224 *
225 * @param {String} key String key corresponding to the value.
226 * @param {String} value String value to store.
227 * @feature Storage
228 * @memberOf hwc.SUPStorage
229 * @example
230 * // Create the SUP Storage
231 * var store = new hwc.SUPStorage ("one");
232 * store.setItem ("foo", "bar"); // add an item.
233 */
234 hwc.SUPStorage.prototype.setItem = function(key, value) {
235 var result;
236 hwc.traceEnteringMethod("hwc.SUPStorage.setItem");
237 key = key ? key : "";
238 value = value ? value : "";
239 try {
240 if (hwc.isWindowsMobile() || hwc.isIOS()) {
241 hwc.postDataToContainer("workflowstorage", "command=setItem&store=" + encodeURIComponent(this.store) + "&shared=" + this.bForSharedStorage + "&key=" +
242 encodeURIComponent(key) + "&value=" + encodeURIComponent(value));
243 }
244 else {
245 if (hwc.isBlackBerry7() && value.length > hwc.SUPStorage.BB7_MAX_STRING_STORAGE_LENGTH) {
246 throw new hwc.SUPStorageException(hwc.SUPStorageException.MAX_SIZE_REACHED, "SUP storage maximum size reached - maximum length of string to store on BB7 is 524000 but attempted to store string of length " + value.length);
247 }
248 if (this.bForSharedStorage) {
249 result = _SharedStorage.setItem(key, value, hwc.versionURLParam);
250 }
251 else {
252 result = SUPStorage.setItem(this.store, key, value);
253 }
254 if (result !== 0) {
255 throw new hwc.SUPStorageException(result, "SUP storage maximum size reached");
256 }
257 }
258 } finally {
259 hwc.traceLeavingMethod("hwc.SUPStorage.setItem");
260 }
261 };
262
263 /**
264 * Removes the key and its associated value from this object. If the
265 * key does not exist, has no effect.
266 *
267 *
268 * @param {String} key String key to remove.
269 * @feature Storage
270 * @memberOf hwc.SUPStorage
271 * @example
272 * // Create the SUP Storage
273 * var store = new hwc.SUPStorage ("one");
274 * store.setItem ("foo", "bar"); // add an item.
275 * store.removeItem ("foo");
276 * result = store.getItem ("food"); // will be null.
277 */
278 hwc.SUPStorage.prototype.removeItem = function(key) {
279 hwc.traceEnteringMethod("hwc.SUPStorage.removeItem");
280 try {
281 key = key ? key : "";
282 if (hwc.isWindowsMobile() || hwc.isIOS()) {
283 hwc.getDataFromContainer("workflowstorage", "&command=removeItem&shared=" + this.bForSharedStorage +
284 "&store=" + encodeURIComponent(this.store) + "&key=" + encodeURIComponent(key));
285 }
286 else {
287 if (this.bForSharedStorage) {
288 _SharedStorage.removeItem(key, hwc.versionURLParam);
289 }
290 else {
291 SUPStorage.removeItem(this.store, key);
292 }
293 }
294 } finally {
295 hwc.traceLeavingMethod("hwc.SUPStorage.removeItem");
296 }
297 };
298
299 /**
300 * Removes all key/value pairs from this object.
301 * @memberOf hwc.SUPStorage
302 * @feature Storage
303 */
304 hwc.SUPStorage.prototype.clear = function() {
305 hwc.traceEnteringMethod("hwc.SUPStorage.clear");
306 try {
307 if (hwc.isWindowsMobile() || hwc.isIOS()) {
308 hwc.getDataFromContainer("workflowstorage", "&command=clear&shared=" + this.bForSharedStorage +
309 "&store=" + encodeURIComponent(this.store));
310 }
311 else {
312 if (this.bForSharedStorage) {
313 _SharedStorage.clear(hwc.versionURLParam);
314 }
315 else {
316 SUPStorage.clear(this.store);
317 }
318 }
319 } finally {
320 hwc.traceLeavingMethod("hwc.SUPStorage.clear");
321 }
322 };
323
324 /**
325 * Exception thrown when Storage space is exceeded.
326 * @feature Storage
327 * @constructor
328 * @memberOf hwc
329 * @param {Integer} code the error code
330 * @param {String} message the error message.
331 */
332 hwc.SUPStorageException = function(code, message) {
333 this.code = code;
334 this.message = message;
335 };
336
337 hwc.SUPStorageException.UNKNOWN_ERROR = 1;
338 hwc.SUPStorageException.MAX_SIZE_REACHED = 2;
339 hwc.SUPStorageException.SHARED_STORAGE_DISABLED = 3;
340
341 // shared storage key.
342 hwc.sharedStorageKey = undefined;
343
344 /**
345 * Method to return the shared storage key defined for the hybrid app by designer. An empty string is returned if the shared storage function is disabled.
346 * @feature Storage
347 * @memberOf hwc
348 * @return {String} the shared storage key.
349 */
350 hwc.getSharedStorageKey = function() {
351 if (hwc.sharedStorageKey === undefined ) {
352 var key = hwc.getQueryVariable("sharedStorageKey");
353 hwc.sharedStorageKey = (key === undefined) ? "":key;
354 }
355 return hwc.sharedStorageKey;
356 };
357
358 /**
359 * Indicates whether the shared storage is enabled for the hybrid app.
360 * @feature Storage
361 * @memberOf hwc
362 * @return {Boolean} true if the shared storage is enabled; false otherwise.
363 */
364 hwc.isSharedStorageEnabled = function() {
365 var key = hwc.getSharedStorageKey();
366 if (key === undefined || key === "") {
367 return false;
368 }
369 else {
370 return true;
371 }
372 };
373
374 /**
375 * Constructs a new SUP shared storage. You can use the returned value to access the shared storage data with the exising SUPStorage interface,
376 * however, the operation only affects the items belonging to the specified shared storage key.
377 * @class
378 * @memberOf hwc
379 * @feature Storage
380 */
381 hwc.SharedStorage = function() {
382 if (hwc.isSharedStorageEnabled() === false ) {
383 throw new hwc.SUPStorageException(hwc.SUPStorageException.SHARED_STORAGE_DISABLED, "Shared storage is disabled");
384 }
385 this.bForSharedStorage = true;
386 this.store = "";
387 };
388
389 hwc.SharedStorage.prototype = new hwc.SUPStorage();
390 hwc.SharedStorage.constructor = hwc.SharedStorage;
391 })(hwc, window);
392
393
394
395