| 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 |
}; |