Debian Codegraph @

closure-library/closure/goog/ui/ac/cachingmatcher.js

raw
1 // Copyright 2013 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 Matcher which maintains a client-side cache on top of some
17 * other matcher.
18 * @author [email protected] (Reiner Pope)
19 */
20
21
22 goog.provide('goog.ui.ac.CachingMatcher');
23
24 goog.require('goog.array');
25 goog.require('goog.async.Throttle');
26 goog.require('goog.ui.ac.ArrayMatcher');
27 goog.require('goog.ui.ac.RenderOptions');
28
29
30
31 /**
32 * A matcher which wraps another (typically slow) matcher and
33 * keeps a client-side cache of the results. For instance, you can use this to
34 * wrap a RemoteArrayMatcher to hide the latency of the underlying matcher
35 * having to make ajax request.
36 *
37 * Objects in the cache are deduped on their stringified forms.
38 *
39 * Note - when the user types a character, they will instantly get a set of
40 * local results, and then some time later, the results from the server will
41 * show up.
42 *
43 * @constructor
44 * @param {!Object} baseMatcher The underlying matcher to use. Must implement
45 * requestMatchingRows.
46 * @final
47 */
48 goog.ui.ac.CachingMatcher = function(baseMatcher) {
49 /** @private {!Array<!Object>}} The cache. */
50 this.rows_ = [];
51
52 /**
53 * Set of stringified rows, for fast deduping. Each element of this.rows_
54 * is stored in rowStrings_ as (' ' + row) to ensure we avoid builtin
55 * properties like 'toString'.
56 * @private {Object<string, boolean>}
57 */
58 this.rowStrings_ = {};
59
60 /**
61 * Maximum number of rows in the cache. If the cache grows larger than this,
62 * the entire cache will be emptied.
63 * @private {number}
64 */
65 this.maxCacheSize_ = 1000;
66
67 /** @private {!Object} The underlying matcher to use. */
68 this.baseMatcher_ = baseMatcher;
69
70 /**
71 * Local matching function.
72 * @private {function(string, number, !Array<!Object>): !Array<!Object>}
73 */
74 this.getMatchesForRows_ = goog.ui.ac.ArrayMatcher.getMatchesForRows;
75
76 /** @private {number} Number of matches to request from the base matcher. */
77 this.baseMatcherMaxMatches_ = 100;
78
79 /** @private {goog.async.Throttle} */
80 this.throttledTriggerBaseMatch_ =
81 new goog.async.Throttle(this.triggerBaseMatch_, 150, this);
82
83 /** @private {string} */
84 this.mostRecentToken_ = '';
85
86 /** @private {Function} */
87 this.mostRecentMatchHandler_ = null;
88
89 /** @private {number} */
90 this.mostRecentMaxMatches_ = 10;
91
92 /**
93 * The set of rows which we last displayed.
94 *
95 * NOTE(reinerp): The need for this is subtle. When a server result comes
96 * back, we don't want to suddenly change the list of results without the user
97 * doing anything. So we make sure to add the new server results to the end of
98 * the currently displayed list.
99 *
100 * We need to keep track of the last rows we displayed, because the "similar
101 * matcher" we use locally might otherwise reorder results.
102 *
103 * @private {Array<!Object>}
104 */
105 this.mostRecentMatches_ = [];
106 };
107
108
109 /**
110 * Sets the number of milliseconds with which to throttle the match requests
111 * on the underlying matcher.
112 *
113 * Default value: 150.
114 *
115 * @param {number} throttleTime .
116 */
117 goog.ui.ac.CachingMatcher.prototype.setThrottleTime = function(throttleTime) {
118 this.throttledTriggerBaseMatch_ =
119 new goog.async.Throttle(this.triggerBaseMatch_, throttleTime, this);
120 };
121
122
123 /**
124 * Sets the maxMatches to use for the base matcher. If the base matcher makes
125 * AJAX requests, it may help to make this a large number so that the local
126 * cache gets populated quickly.
127 *
128 * Default value: 100.
129 *
130 * @param {number} maxMatches The value to set.
131 */
132 goog.ui.ac.CachingMatcher.prototype.setBaseMatcherMaxMatches = function(
133 maxMatches) {
134 this.baseMatcherMaxMatches_ = maxMatches;
135 };
136
137
138 /**
139 * Sets the maximum size of the local cache. If the local cache grows larger
140 * than this size, it will be emptied.
141 *
142 * Default value: 1000.
143 *
144 * @param {number} maxCacheSize .
145 */
146 goog.ui.ac.CachingMatcher.prototype.setMaxCacheSize = function(maxCacheSize) {
147 this.maxCacheSize_ = maxCacheSize;
148 };
149
150
151 /**
152 * Sets the local matcher to use.
153 *
154 * The local matcher should be a function with the same signature as
155 * {@link goog.ui.ac.ArrayMatcher.getMatchesForRows}, i.e. its arguments are
156 * searchToken, maxMatches, rowsToSearch; and it returns a list of matching
157 * rows.
158 *
159 * Default value: {@link goog.ui.ac.ArrayMatcher.getMatchesForRows}.
160 *
161 * @param {function(string, number, !Array<!Object>): !Array<!Object>}
162 * localMatcher
163 */
164 goog.ui.ac.CachingMatcher.prototype.setLocalMatcher = function(localMatcher) {
165 this.getMatchesForRows_ = localMatcher;
166 };
167
168
169 /**
170 * Function used to pass matches to the autocomplete.
171 * @param {string} token Token to match.
172 * @param {number} maxMatches Max number of matches to return.
173 * @param {Function} matchHandler callback to execute after matching.
174 */
175 goog.ui.ac.CachingMatcher.prototype.requestMatchingRows = function(
176 token, maxMatches, matchHandler) {
177 this.mostRecentMaxMatches_ = maxMatches;
178 this.mostRecentToken_ = token;
179 this.mostRecentMatchHandler_ = matchHandler;
180 this.throttledTriggerBaseMatch_.fire();
181
182 var matches = this.getMatchesForRows_(token, maxMatches, this.rows_);
183 matchHandler(token, matches);
184 this.mostRecentMatches_ = matches;
185 };
186
187
188 /** Clears the cache. */
189 goog.ui.ac.CachingMatcher.prototype.clearCache = function() {
190 this.rows_ = [];
191 this.rowStrings_ = {};
192 };
193
194
195 /**
196 * Adds the specified rows to the cache.
197 * @param {!Array<!Object>} rows .
198 * @private
199 */
200 goog.ui.ac.CachingMatcher.prototype.addRows_ = function(rows) {
201 goog.array.forEach(rows, function(row) {
202 // The ' ' prefix is to avoid colliding with builtins like toString.
203 if (!this.rowStrings_[' ' + row]) {
204 this.rows_.push(row);
205 this.rowStrings_[' ' + row] = true;
206 }
207 }, this);
208 };
209
210
211 /**
212 * Checks if the cache is larger than the maximum cache size. If so clears it.
213 * @private
214 */
215 goog.ui.ac.CachingMatcher.prototype.clearCacheIfTooLarge_ = function() {
216 if (this.rows_.length > this.maxCacheSize_) {
217 this.clearCache();
218 }
219 };
220
221
222 /**
223 * Triggers a match request against the base matcher. This function is
224 * unthrottled, so don't call it directly; instead use
225 * this.throttledTriggerBaseMatch_.
226 * @private
227 */
228 goog.ui.ac.CachingMatcher.prototype.triggerBaseMatch_ = function() {
229 this.baseMatcher_.requestMatchingRows(
230 this.mostRecentToken_, this.baseMatcherMaxMatches_,
231 goog.bind(this.onBaseMatch_, this));
232 };
233
234
235 /**
236 * Handles a match response from the base matcher.
237 * @param {string} token The token against which the base match was called.
238 * @param {!Array<!Object>} matches The matches returned by the base matcher.
239 * @private
240 */
241 goog.ui.ac.CachingMatcher.prototype.onBaseMatch_ = function(token, matches) {
242 // NOTE(reinerp): The user might have typed some more characters since the
243 // base matcher request was sent out, which manifests in that token might be
244 // older than this.mostRecentToken_. We make sure to do our local matches
245 // using this.mostRecentToken_ rather than token so that we display results
246 // relevant to what the user is seeing right now.
247
248 // NOTE(reinerp): We compute a diff between the currently displayed results
249 // and the new results we would get now that the server results have come
250 // back. Using this diff, we make sure the new results are only added to the
251 // end of the list of results. See the documentation on
252 // this.mostRecentMatches_ for details
253
254 this.addRows_(matches);
255
256 var oldMatchesSet = {};
257 goog.array.forEach(this.mostRecentMatches_, function(match) {
258 // The ' ' prefix is to avoid colliding with builtins like toString.
259 oldMatchesSet[' ' + match] = true;
260 });
261 var newMatches = this.getMatchesForRows_(
262 this.mostRecentToken_, this.mostRecentMaxMatches_, this.rows_);
263 newMatches = goog.array.filter(
264 newMatches, function(match) { return !(oldMatchesSet[' ' + match]); });
265 newMatches = this.mostRecentMatches_.concat(newMatches)
266 .slice(0, this.mostRecentMaxMatches_);
267
268 this.mostRecentMatches_ = newMatches;
269
270 // We've gone to the effort of keeping the existing rows as before, so let's
271 // make sure to keep them highlighted.
272 var options = new goog.ui.ac.RenderOptions();
273 options.setPreserveHilited(true);
274 this.mostRecentMatchHandler_(this.mostRecentToken_, newMatches, options);
275
276 // We clear the cache *after* running the local match, so we don't
277 // suddenly remove results just because the remote match came back.
278 this.clearCacheIfTooLarge_();
279 };