Source: lib/offline/db_engine.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  18. goog.provide('shaka.offline.DBEngine');
  20. goog.require('goog.asserts');
  21. goog.require('shaka.log');
  22. goog.require('shaka.util.Error');
  23. goog.require('shaka.util.Functional');
  24. goog.require('shaka.util.IDestroyable');
  25. goog.require('shaka.util.PublicPromise');
  29. /**
  30.  * This manages all operations on an IndexedDB.  This wraps all operations
  31.  * in Promises.  All Promises will resolve once the transaction has completed.
  32.  * Depending on the browser, this may or may not be after the data is flushed
  33.  * to disk.  https://goo.gl/zMOeJc
  34.  *
  35.  * @struct
  36.  * @constructor
  37.  * @implements {shaka.util.IDestroyable}
  38.  */
  39. shaka.offline.DBEngine = function() {
  40.   /** @private {IDBDatabase} */
  41.   this.db_ = null;
  43.   /** @private {!Array.<shaka.offline.DBEngine.Operation>} */
  44.   this.operations_ = [];
  46.   /** @private {!Object.<string, number>} */
  47.   this.currentIdMap_ = {};
  48. };
  51. /**
  52.  * @typedef {{
  53.  *   transaction: !IDBTransaction,
  54.  *   promise: !shaka.util.PublicPromise
  55.  * }}
  56.  *
  57.  * @property {!IDBTransaction} transaction
  58.  *   The transaction that this operation is using.
  59.  * @property {!shaka.util.PublicPromise} promise
  60.  *   The promise associated with the operation.
  61.  */
  62. shaka.offline.DBEngine.Operation;
  65. /** @private {string} */
  66. shaka.offline.DBEngine.DB_NAME_ = 'shaka_offline_db';
  69. /** @private @const {number} */
  70. shaka.offline.DBEngine.DB_VERSION_ = 1;
  73. /**
  74.  * Determines if the browsers supports IndexedDB.
  75.  * @return {boolean}
  76.  */
  77. shaka.offline.DBEngine.isSupported = function() {
  78.   return window.indexedDB != null;
  79. };
  82. /**
  83.  * Delete the database.  There must be no open connections to the database.
  84.  * @return {!Promise}
  85.  */
  86. shaka.offline.DBEngine.deleteDatabase = function() {
  87.   if (!window.indexedDB)
  88.     return Promise.resolve();
  89.   var request =
  90.       window.indexedDB.deleteDatabase(shaka.offline.DBEngine.DB_NAME_);
  92.   var p = new shaka.util.PublicPromise();
  93.   request.onsuccess = function(event) {
  94.     goog.asserts.assert(event.newVersion == null, 'Unexpected database update');
  95.     p.resolve();
  96.   };
  97.   request.onerror = shaka.offline.DBEngine.onError_.bind(null, request, p);
  98.   return p;
  99. };
  102. /**
  103.  * Gets whether the DBEngine is initialized.
  104.  *
  105.  * @return {boolean}
  106.  */
  107. shaka.offline.DBEngine.prototype.initialized = function() {
  108.   return this.db_ != null;
  109. };
  112. /**
  113.  * Initializes the database and creates and required tables.
  114.  *
  115.  * @param {!Object.<string, string>} storeMap
  116.  *   A map of store name to the key path.
  117.  * @return {!Promise}
  118.  */
  119. shaka.offline.DBEngine.prototype.init = function(storeMap) {
  120.   goog.asserts.assert(!this.db_, 'Already initialized');
  121.   var DBEngine = shaka.offline.DBEngine;
  122.   if (!DBEngine.isSupported()) {
  123.     return Promise.reject(
  124.         new shaka.util.Error(
  125.             shaka.util.Error.Category.STORAGE,
  126.             shaka.util.Error.Code.INDEXED_DB_NOT_SUPPORTED));
  127.   }
  129.   var indexedDB = window.indexedDB;
  130.   var request = indexedDB.open(DBEngine.DB_NAME_, DBEngine.DB_VERSION_);
  132.   var promise = new shaka.util.PublicPromise();
  133.   request.onupgradeneeded = function(event) {
  134.     var db = event.target.result;
  135.     goog.asserts.assert(event.oldVersion == 0,
  136.                         'Must be upgrading from version 0');
  137.     goog.asserts.assert(db.objectStoreNames.length == 0,
  138.                         'Version 0 database should be empty');
  139.     for (var name in storeMap) {
  140.       db.createObjectStore(name, {keyPath: storeMap[name]});
  141.     }
  142.   };
  143.   request.onsuccess = (function(event) {
  144.     this.db_ = event.target.result;
  145.     promise.resolve();
  146.   }.bind(this));
  147.   request.onerror = DBEngine.onError_.bind(null, request, promise);
  149.   return promise.then(function() {
  150.     // For each store, get the next ID and store in the map.
  151.     var stores = Object.keys(storeMap);
  152.     return Promise.all(stores.map(function(store) {
  153.       return this.getNextId_(store).then(function(id) {
  154.         this.currentIdMap_[store] = id;
  155.       }.bind(this));
  156.     }.bind(this)));
  157.   }.bind(this));
  158. };
  161. /** @override */
  162. shaka.offline.DBEngine.prototype.destroy = function() {
  163.   return Promise.all(this.operations_.map(function(op) {
  164.     try {
  165.       // If the transaction is considered finished but has not called the
  166.       // callbacks yet, it will still be in the list and this call will fail.
  167.       // Simply ignore errors.
  168.       op.transaction.abort();
  169.     } catch (e) {}
  171.     var Functional = shaka.util.Functional;
  172.     return op.promise.catch(Functional.noop);
  173.   })).then(function() {
  174.     goog.asserts.assert(this.operations_.length == 0,
  175.                         'All operations should have been closed');
  176.     if (this.db_) {
  177.       this.db_.close();
  178.       this.db_ = null;
  179.     }
  180.   }.bind(this));
  181. };
  184. /**
  185.  * Gets the item with the given ID in the store.
  186.  *
  187.  * @param {string} storeName
  188.  * @param {number} key
  189.  * @return {!Promise.<T>}
  190.  * @template T
  191.  */
  192. shaka.offline.DBEngine.prototype.get = function(storeName, key) {
  193.   return this.createOperation_(storeName, 'readonly', function(store) {
  194.     return store.get(key);
  195.   });
  196. };
  199. /**
  200.  * Calls the given callback for each value in the store.  The promise will
  201.  * resolve after all items have been traversed.
  202.  *
  203.  * @param {string} storeName
  204.  * @param {function(T)} callback
  205.  * @return {!Promise}
  206.  * @template T
  207.  */
  208. shaka.offline.DBEngine.prototype.forEach = function(storeName, callback) {
  209.   return this.createOperation_(storeName, 'readonly', function(store) {
  210.     return store.openCursor();
  211.   }, function(/** IDBCursor */ cursor) {
  212.     if (!cursor) return;
  214.     callback(cursor.value);
  215.     cursor.continue();
  216.   });
  217. };
  220. /**
  221.  * Adds or updates the given value in the store.
  222.  *
  223.  * @param {string} storeName
  224.  * @param {!Object} value
  225.  * @return {!Promise}
  226.  */
  227. shaka.offline.DBEngine.prototype.insert = function(storeName, value) {
  228.   return this.createOperation_(storeName, 'readwrite', function(store) {
  229.     return store.put(value);
  230.   });
  231. };
  234. /**
  235.  * Removes the item with the given key.
  236.  *
  237.  * @param {string} storeName
  238.  * @param {number} key
  239.  * @return {!Promise}
  240.  */
  241. shaka.offline.DBEngine.prototype.remove = function(storeName, key) {
  242.   return this.createOperation_(storeName, 'readwrite', function(store) {
  243.     return store.delete(key);
  244.   });
  245. };
  248. /**
  249.  * Removes all items for which the given predicate returns true.
  250.  *
  251.  * @param {string} storeName
  252.  * @param {function(T):boolean} callback
  253.  * @return {!Promise.<number>}
  254.  * @template T
  255.  */
  256. shaka.offline.DBEngine.prototype.removeWhere = function(storeName, callback) {
  257.   var async = [];
  258.   return this.createOperation_(storeName, 'readwrite', function(store) {
  259.     return store.openCursor();
  260.   }, function(/** IDBCursor */ cursor) {
  261.     if (!cursor) return;
  263.     if (callback(cursor.value)) {
  264.       var request = cursor.delete();
  265.       var p = new shaka.util.PublicPromise();
  266.       request.onsuccess = p.resolve;
  267.       request.onerror = shaka.offline.DBEngine.onError_.bind(null, request, p);
  268.       async.push(p);
  269.     }
  270.     cursor.continue();
  271.   }).then(function() {
  272.     return Promise.all(async);
  273.   }).then(function() {
  274.     return async.length;
  275.   });
  276. };
  279. /**
  280.  * Reserves the next ID and returns it.
  281.  *
  282.  * @param {string} storeName
  283.  * @return {number}
  284.  */
  285. shaka.offline.DBEngine.prototype.reserveId = function(storeName) {
  286.   goog.asserts.assert(storeName in this.currentIdMap_,
  287.                       'Store name must be passed to init()');
  288.   return this.currentIdMap_[storeName]++;
  289. };
  292. /**
  293.  * Gets the ID to start at.
  294.  *
  295.  * @param {string} storeName
  296.  * @return {!Promise.<number>}
  297.  * @private
  298.  */
  299. shaka.offline.DBEngine.prototype.getNextId_ = function(storeName) {
  300.   var ret = 0;
  301.   return this.createOperation_(storeName, 'readonly', function(store) {
  302.     return store.openCursor(null, 'prev');
  303.   }, function(/** IDBCursor */ cursor) {
  304.     if (cursor)
  305.       ret = cursor.key + 1;
  306.   }).then(function() { return ret; });
  307. };
  310. /**
  311.  * Creates a new transaction for the given store name and calls the given
  312.  * callback to create a request.  It then wraps the given request in an
  313.  * operation and returns the resulting promise.  The Promise resolves when
  314.  * the transaction is complete, which will be after opt_success is called.
  315.  *
  316.  * @param {string} storeName
  317.  * @param {string} type
  318.  * @param {function(!IDBObjectStore):!IDBRequest} createRequest
  319.  * @param {(function(*))=} opt_success The value of onsuccess for the request.
  320.  * @return {!Promise}
  321.  * @private
  322.  */
  323. shaka.offline.DBEngine.prototype.createOperation_ = function(
  324.     storeName, type, createRequest, opt_success) {
  325.   goog.asserts.assert(this.db_, 'Must not be destroyed');
  326.   goog.asserts.assert(type == 'readonly' || type == 'readwrite',
  327.                       'Type must be "readonly" or "readwrite"');
  329.   var trans = this.db_.transaction([storeName], type);
  330.   var request = createRequest(trans.objectStore(storeName));
  332.   var p = new shaka.util.PublicPromise();
  333.   if (opt_success)
  334.     request.onsuccess = function(event) { opt_success(event.target.result); };
  335.   request.onerror = function(event) {
  336.     shaka.log.info('The request unexpectedly failed',
  337.                    request.error ? request.error.message : 'unknown error');
  338.   };
  340.   var op = {transaction: trans, promise: p};
  341.   this.operations_.push(op);
  343.   // Only remove the transaction once it has completed, which may be after the
  344.   // request is complete (e.g. it may need to write to disk).
  345.   var removeOp = (function() {
  346.     var i = this.operations_.indexOf(op);
  347.     goog.asserts.assert(i >= 0, 'Operation must be in the list.');
  348.     this.operations_.splice(i, 1);
  349.   }.bind(this));
  350.   trans.oncomplete = function(event) {
  351.     removeOp();
  352.     p.resolve(request.result);
  353.   };
  354.   trans.onerror = function(event) {
  355.     // Otherwise Firefox will raise an error which will cause a karma failure.
  356.     // This will not stop the onabort callback from firing.
  357.     event.preventDefault();
  358.   };
  359.   // We will see an onabort call via:
  360.   //   1. request error -> transaction error -> transaction abort
  361.   //   2. transaction commit fail -> transaction abort
  362.   // As any transaction error will result in an abort, it is better to listen
  363.   // for an abort so that we will catch all failed transaction operations.
  364.   trans.onabort = function(event) {
  365.     removeOp();
  366.     shaka.offline.DBEngine.onError_(request, p, event);
  367.   };
  368.   return p;
  369. };
  372. /**
  373.  * Rejects the given Promise with an unknown error.
  374.  *
  375.  * @param {!IDBRequest} request
  376.  * @param {!shaka.util.PublicPromise} promise
  377.  * @param {Event} event
  378.  * @private
  379.  */
  380. shaka.offline.DBEngine.onError_ = function(request, promise, event) {
  381.   // |request.error| can be null as per 3.3.4 point 2 of the W3 spec. When a
  382.   // request does not have an error and is passed here it is because it was from
  383.   // |transaction.onabort| and therefore not an actual error.
  384.   if (!request.error || request.error.name == 'AbortError') {
  385.     promise.reject(new shaka.util.Error(
  386.         shaka.util.Error.Category.STORAGE,
  387.         shaka.util.Error.Code.OPERATION_ABORTED));
  388.   } else {
  389.     promise.reject(new shaka.util.Error(
  390.         shaka.util.Error.Category.STORAGE,
  391.         shaka.util.Error.Code.INDEXED_DB_ERROR, request.error));
  392.   }
  394.   // Firefox will raise an error which will cause a karma failure.
  395.   event.preventDefault();
  396. };