1
// Licensed to the Software Freedom Conservancy (SFC) under one
2
// or more contributor license agreements.  See the NOTICE file
3
// distributed with this work for additional information
4
// regarding copyright ownership.  The SFC licenses this file
5
// to you under the Apache License, Version 2.0 (the
6
// "License"); you may not use this file except in compliance
7
// with the License.  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,
12
// software distributed under the License is distributed on an
13
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14
// KIND, either express or implied.  See the License for the
15
// specific language governing permissions and limitations
16
// under the License.
17

18
/**
19
 * @fileoverview Atoms for executing SQL queries on web client database.
20
 *
21
 */
22

23
goog.provide('bot.storage.database');
24
goog.provide('bot.storage.database.ResultSet');
25

26
goog.require('bot');
27
goog.require('bot.Error');
28
goog.require('bot.ErrorCode');
29

30

31
/**
32
 * Opens the database to access its contents. This function will create the
33
 * database if it does not exist. For details,
34
 * @see http://www.w3.org/TR/webdatabase/#databases
35
 *
36
 * @param {string} databaseName The name of the database.
37
 * @param {string=} opt_version The expected database version to be opened;
38
 *     defaults to the empty string.
39
 * @param {string=} opt_displayName The name to be displayed to the user;
40
 *     defaults to the databaseName.
41
 * @param {number=} opt_size The estimated initial quota size of the database;
42
 *     default value is 5MB.
43
 * @param {!Window=} opt_window The window associated with the database;
44
 *     defaults to the main window.
45
 * @return {!Database} The object to access the web database.
46
 *
47
 */
48
bot.storage.database.openOrCreate = function(databaseName, opt_version,
49
    opt_displayName, opt_size, opt_window) {
50
  var version = opt_version || '';
51
  var displayName = opt_displayName || (databaseName + 'name');
52
  var size = opt_size || 5 * 1024 * 1024;
53
  var win = opt_window || bot.getWindow();
54

55
  return win.openDatabase(databaseName, version, displayName, size);
56
};
57

58

59
/**
60
 * It executes a single SQL query on a given web database storage.
61
 *
62
 * @param {string} databaseName The name of the database.
63
 * @param {string} query The SQL statement.
64
 * @param {!Array.<*>} args Arguments needed for the SQL statement.
65
 * @param {!function(!SQLTransaction, !bot.storage.database.ResultSet)}
66
 *     queryResultCallback Callback function to be invoked on successful query
67
 *     statement execution.
68
 * @param {!function(!SQLError)} txErrorCallback
69
 *     Callback function to be invoked on transaction (commit) failure.
70
 * @param {!function()=} opt_txSuccessCallback
71
 *     Callback function to be invoked on successful transaction execution.
72
 * @param {function(!SQLTransaction, !SQLError)=} opt_queryErrorCallback
73
 *     Callback function to be invoked on successful query statement execution.
74
 * @see http://www.w3.org/TR/webdatabase/#executing-sql-statements
75
 */
76
bot.storage.database.executeSql = function(databaseName, query, args,
77
    queryResultCallback, txErrorCallback, opt_txSuccessCallback,
78
    opt_queryErrorCallback) {
79

80
  var db;
81

82
  try {
83
    db = bot.storage.database.openOrCreate(databaseName);
84
  } catch (e) {
85
    throw new bot.Error(bot.ErrorCode.UNKNOWN_ERROR, e.message);
86
  }
87

88
  var queryCallback = function(tx, result) {
89
    var wrappedResult = new bot.storage.database.ResultSet(result);
90
    queryResultCallback(tx, wrappedResult);
91
  };
92

93
  var transactionCallback = function(tx) {
94
    tx.executeSql(query, args, queryCallback, opt_queryErrorCallback);
95
  };
96

97
  db.transaction(transactionCallback, txErrorCallback,
98
      opt_txSuccessCallback);
99
};
100

101

102

103
/**
104
 * A wrapper of the SQLResultSet object returned by the SQL statement.
105
 *
106
 * @param {!SQLResultSet} sqlResultSet The original SQLResultSet object.
107
 * @constructor
108
 */
109
bot.storage.database.ResultSet = function(sqlResultSet) {
110

111
  /**
112
   * The database rows returned from the SQL query.
113
   * @type {!Array.<*>}
114
   */
115
  this.rows = [];
116
  for (var i = 0; i < sqlResultSet.rows.length; i++) {
117
    this.rows[i] = sqlResultSet.rows.item(i);
118
  }
119

120
  /**
121
   * The number of rows that were changed by the SQL statement
122
   * @type {number}
123
   */
124
  this.rowsAffected = sqlResultSet.rowsAffected;
125

126
  /**
127
   * The row ID of the row that the SQLResultSet object's SQL statement
128
   * inserted into the database, if the statement inserted a row; else
129
   * it is assigned to -1. Originally, accessing insertId attribute of
130
   * a SQLResultSet object returns the exception INVALID_ACCESS_ERR
131
   * if no rows are inserted.
132
   * @type {number}
133
   */
134
  this.insertId = -1;
135
  try {
136
    this.insertId = sqlResultSet.insertId;
137
  } catch (error) {
138
    // If accessing sqlResultSet.insertId results in INVALID_ACCESS_ERR
139
    // exception, this.insertId will be assigned to -1.
140
  }
141
};
142

143