Updated

master/closure-library/closure/goog/db/cursor.js

@@ -0,0 +1,175 @@
+// Copyright 2012 The Closure Library Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS-IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @fileoverview Wrapper for a IndexedDB cursor.
+ *
+ */
+
+
+goog.provide('goog.db.Cursor');
+
+goog.require('goog.async.Deferred');
+goog.require('goog.db.Error');
+goog.require('goog.debug');
+goog.require('goog.events.EventTarget');
+
+
+
+/**
+ * Creates a new IDBCursor wrapper object. Should not be created directly,
+ * access cursor through object store.
+ * @see goog.db.ObjectStore#openCursor
+ *
+ * @constructor
+ * @extends {goog.events.EventTarget}
+ */
+goog.db.Cursor = function() {
+  goog.base(this);
+};
+goog.inherits(goog.db.Cursor, goog.events.EventTarget);
+
+
+/**
+ * Underlying IndexedDB cursor object.
+ *
+ * @type {IDBCursor}
+ * @private
+ */
+goog.db.Cursor.prototype.cursor_ = null;
+
+
+/**
+ * Advances the cursor to the next position along its direction. When new data
+ * is availible, the NEW_DATA event will be fired. If the cursor has reached the
+ * end of the range it will fire the COMPLETE event. If opt_key is specified it
+ * will advance to the key it matches in its direction.
+ *
+ * This wraps the native #continue method on the underlying object.
+ *
+ * @param {!Object=} opt_key The optional key to advance to.
+ */
+goog.db.Cursor.prototype.next = function(opt_key) {
+  if (opt_key) {
+    this.cursor_['continue'](opt_key);
+  } else {
+    this.cursor_['continue']();
+  }
+};
+
+
+/**
+ * Updates the value at the current position of the cursor in the object store.
+ * If the cursor points to a value that has just been deleted, a new value is
+ * created.
+ *
+ * @param {!Object} value The value to be stored.
+ * @return {!goog.async.Deferred} The resulting deferred request.
+ */
+goog.db.Cursor.prototype.update = function(value) {
+  var msg = 'updating via cursor with value ';
+  var d = new goog.async.Deferred();
+  var request;
+
+  try {
+    request = this.cursor_.update(value);
+  } catch (err) {
+    msg += goog.debug.deepExpose(value);
+    d.errback(new goog.db.Error(err.code, msg));
+    return d;
+  }
+  request.onsuccess = function(ev) {
+    d.callback();
+  };
+  request.onerror = function(ev) {
+    msg += goog.debug.deepExpose(value);
+    d.errback(new goog.db.Error(
+        (/** @type {IDBRequest} */ (ev.target)).errorCode, msg));
+  };
+  return d;
+};
+
+
+/**
+ * Deletes the value at the cursor's position, without changing the cursor's
+ * position. Once the value is deleted, the cursor's value is set to null.
+ *
+ * @return {!goog.async.Deferred} The resulting deferred request.
+ */
+goog.db.Cursor.prototype.remove = function() {
+  var msg = 'deleting via cursor';
+  var d = new goog.async.Deferred();
+  var request;
+
+  try {
+    request = this.cursor_['delete']();
+  } catch (err) {
+    d.errback(new goog.db.Error(err.code, msg));
+    return d;
+  }
+  request.onsuccess = function(ev) {
+    d.callback();
+  };
+  request.onerror = function(ev) {
+    d.errback(new goog.db.Error(
+        (/** @type {IDBRequest} */ (ev.target)).errorCode, msg));
+  };
+  return d;
+};
+
+
+/**
+ * @return {Object} The value for the value at the cursor's position. Undefined
+ *     if no current value, or null if value has just been deleted.
+ */
+goog.db.Cursor.prototype.getValue = function() {
+  return this.cursor_['value'];
+};
+
+
+/**
+ * @return {*} The key for the value at the cursor's position. If the
+ *     cursor is outside its range, this is undefined.
+ */
+goog.db.Cursor.prototype.getKey = function() {
+  return this.cursor_.key;
+};
+
+
+/**
+ * Possible cursor directions.
+ * @see http://www.w3.org/TR/IndexedDB/#idl-def-IDBCursor
+ *
+ * @enum {number}
+ */
+goog.db.Cursor.Direction = {
+  NEXT: 0,
+  NEXT_NO_DUPLICATE: 1,
+  PREV: 2,
+  PREV_NO_DUPLICATE: 3
+};
+
+
+/**
+ * Event types that the cursor can dispatch. COMPLETE events are dispatched when
+ * a cursor is depleted of values, a NEW_DATA event if there is new data
+ * availible, and ERROR if an error occurred.
+ *
+ * @enum {string}
+ */
+goog.db.Cursor.EventType = {
+  COMPLETE: 'c',
+  ERROR: 'e',
+  NEW_DATA: 'n'
+};