Debian Codegraph @

closure-library/closure/goog/storage/richstorage.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 a convenient API for data with attached metadata
17 * persistence. You probably don't want to use this class directly as it
18 * does not save any metadata by itself. It only provides the necessary
19 * infrastructure for subclasses that need to save metadata along with
20 * values stored.
21 *
22 */
23
24 goog.provide('goog.storage.RichStorage');
25 goog.provide('goog.storage.RichStorage.Wrapper');
26
27 goog.require('goog.storage.ErrorCode');
28 goog.require('goog.storage.Storage');
29
30
31
32 /**
33 * Provides a storage for data with attached metadata.
34 *
35 * @param {!goog.storage.mechanism.Mechanism} mechanism The underlying
36 * storage mechanism.
37 * @constructor
38 * @struct
39 * @extends {goog.storage.Storage}
40 */
41 goog.storage.RichStorage = function(mechanism) {
42 goog.storage.RichStorage.base(this, 'constructor', mechanism);
43 };
44 goog.inherits(goog.storage.RichStorage, goog.storage.Storage);
45
46
47 /**
48 * Metadata key under which the actual data is stored.
49 *
50 * @type {string}
51 * @protected
52 */
53 goog.storage.RichStorage.DATA_KEY = 'data';
54
55
56
57 /**
58 * Wraps a value so metadata can be associated with it. You probably want
59 * to use goog.storage.RichStorage.Wrapper.wrapIfNecessary to avoid multiple
60 * embeddings.
61 *
62 * @param {*} value The value to wrap.
63 * @constructor
64 * @final
65 */
66 goog.storage.RichStorage.Wrapper = function(value) {
67 this[goog.storage.RichStorage.DATA_KEY] = value;
68 };
69
70
71 /**
72 * Convenience method for wrapping a value so metadata can be associated with
73 * it. No-op if the value is already wrapped or is undefined.
74 *
75 * @param {*} value The value to wrap.
76 * @return {(!goog.storage.RichStorage.Wrapper|undefined)} The wrapper.
77 */
78 goog.storage.RichStorage.Wrapper.wrapIfNecessary = function(value) {
79 if (!goog.isDef(value) || value instanceof goog.storage.RichStorage.Wrapper) {
80 return /** @type {(!goog.storage.RichStorage.Wrapper|undefined)} */ (value);
81 }
82 return new goog.storage.RichStorage.Wrapper(value);
83 };
84
85
86 /**
87 * Unwraps a value, any metadata is discarded (not returned). You might want to
88 * use goog.storage.RichStorage.Wrapper.unwrapIfPossible to handle cases where
89 * the wrapper is missing.
90 *
91 * @param {!Object} wrapper The wrapper.
92 * @return {*} The wrapped value.
93 */
94 goog.storage.RichStorage.Wrapper.unwrap = function(wrapper) {
95 var value = wrapper[goog.storage.RichStorage.DATA_KEY];
96 if (!goog.isDef(value)) {
97 throw goog.storage.ErrorCode.INVALID_VALUE;
98 }
99 return value;
100 };
101
102
103 /**
104 * Convenience method for unwrapping a value. Returns undefined if the
105 * wrapper is missing.
106 *
107 * @param {(!Object|undefined)} wrapper The wrapper.
108 * @return {*} The wrapped value or undefined.
109 */
110 goog.storage.RichStorage.Wrapper.unwrapIfPossible = function(wrapper) {
111 if (!wrapper) {
112 return undefined;
113 }
114 return goog.storage.RichStorage.Wrapper.unwrap(wrapper);
115 };
116
117
118 /** @override */
119 goog.storage.RichStorage.prototype.set = function(key, value) {
120 goog.storage.RichStorage.base(
121 this, 'set', key,
122 goog.storage.RichStorage.Wrapper.wrapIfNecessary(value));
123 };
124
125
126 /**
127 * Get an item wrapper (the item and its metadata) from the storage.
128 *
129 * WARNING: This returns an Object, which once used to be
130 * goog.storage.RichStorage.Wrapper. This is due to the fact
131 * that deserialized objects lose type information and it
132 * is hard to do proper typecasting in JavaScript. Be sure
133 * you know what you are doing when using the returned value.
134 *
135 * @param {string} key The key to get.
136 * @return {(!Object|undefined)} The wrapper, or undefined if not found.
137 */
138 goog.storage.RichStorage.prototype.getWrapper = function(key) {
139 var wrapper = goog.storage.RichStorage.superClass_.get.call(this, key);
140 if (!goog.isDef(wrapper) || wrapper instanceof Object) {
141 return /** @type {(!Object|undefined)} */ (wrapper);
142 }
143 throw goog.storage.ErrorCode.INVALID_VALUE;
144 };
145
146
147 /** @override */
148 goog.storage.RichStorage.prototype.get = function(key) {
149 return goog.storage.RichStorage.Wrapper.unwrapIfPossible(
150 this.getWrapper(key));
151 };