Merge branch 'common-src' into master-src

Major changes from common-src:
Implement pre-population ref: #10/#172
Choose DB location to make iCloud backup optional ref: #16/#143
Fix db close conditions & prevent double-marshaling of data ref: pull #170

README.md

@@ -6,34 +6,16 @@ License for Android & WP(8) versions: MIT or Apache 2.0
 
 License for iOS version: MIT only
 
-## WARNING: breaking change for Android version
-
-The automatic "`.db`" database file extension is [now removed](https://github.com/brodysoft/Cordova-SQLitePlugin/commit/3723cfc2dc933ae128fe9d5998efe4d76fcb0370) for the Android version, for consistency with the other versions. For an existing app, you may have to open an existing database like:
-
-```js
-var db = window.sqlitePlugin.openDatabase({name: "my.db"});
-```
-
-Also the threading model is changed as described below.
-
 ## Status
 
-- Please use the [Cordova-SQLitePlugin forum](http://groups.google.com/group/Cordova-SQLitePlugin) for community support
-- Commercial support is available for SQLCipher integration with Android & iOS versions
+- Please use the [Cordova-SQLitePlugin forum](http://groups.google.com/group/Cordova-SQLitePlugin) or [raise a new issue](https://github.com/brodysoft/Cordova-SQLitePlugin/issues/new) for community support
+- SQLCipher integration is not supported by this project, will be supported in a separate project.
 
 ## Announcements
 
-- Issue with multi-page apps is fixed for Android
-- WP(8) version is now working with CSharp-SQLite library (may use DLL or rebuild from source) and passing most of the tests.
-- Changes to background processing:
- - The `dbType` option is now removed;
- - Android version is now using one thread per db;
- - for iOS version backround processing using a thread pool is now mandatory;
- - for WP(8) version, background processing with one thread per transaction.
+- New `openDatabase` and `deleteDatabase` `location` option to select database location (iOS *only*) and disable iCloud backup
+- Pre-populated databases support for Android & iOS is now integrated, usage described below
 - Fixes to work with PouchDB by [@nolanlawson](https://github.com/nolanlawson)
-- Forum renamed to: [Cordova-SQLitePlugin forum](http://groups.google.com/group/Cordova-SQLitePlugin)
-- New location: https://github.com/brodysoft/Cordova-SQLitePlugin
-- iOS version can now be built with either ARC or MRC.
 
 ## Highlights
 
@@ -43,8 +25,8 @@ Also the threading model is changed as described below.
 - As described in [this posting](http://brodyspark.blogspot.com/2012/12/cordovaphonegap-sqlite-plugins-offer.html):
  - Keeps sqlite database in a user data location that is known, can be reconfigured, and iOS will be backed up by iCloud.
  - No 5MB maximum, more information at: http://www.sqlite.org/limits.html
-- Android & iOS working with [SQLCipher](http://sqlcipher.net) for encryption (see below)
 - Android is supported back to SDK 10 (a.k.a. Gingerbread, Android 2.3.3); Support for older versions is available upon request.
+- Pre-populated database option (usage described below)
 
 ## Some apps using Cordova/PhoneGap SQLitePlugin
 
@@ -55,36 +37,24 @@ Also the threading model is changed as described below.
 
 ## Known issues
 
-- Deleting a database is not (yet) implemented for WP(8).
-- db.executeSql() calls callback multiple times
-- issues with db.close() & sqlitePlugin.deleteDatabase()
-- using web workers is currently not supported and known to be broken on Android
-- INSERT statement that affects multiple rows (due to SELECT cause or using triggers, for example) does not report proper rowsAffected on Android
+- Using web workers is currently not supported and known to be broken on Android.
+- Triggers are only supported for iOS, known to be broken on Android.
+- INSERT statement that affects multiple rows (due to SELECT cause or using triggers, for example) does not report proper rowsAffected on Android.
 
 ## Other limitations
 
 - The db version, display name, and size parameter values are not supported and will be ignored.
 - The sqlite plugin will not work before the callback for the "deviceready" event has been fired, as described in **Usage**.
-- For iOS, iCloud backup is NOT optional and should be.
 - The Android version cannot work with more than 100 open db files due to its threading model.
-- Missing db creation callback
 
 ## Limited support (testing needed)
 
-- DB Triggers (...)
 - Multi-page apps on WP(8)
+- DB Triggers (as described above - known to be broken for Android)
 
 ## Other versions
 
-- Pre-populated database support for Android & iOS: https://github.com/RikshaDriver/Cordova-PrePopulated-SQLitePlugin
-- Original version for iOS, with a different API: https://github.com/davibe/Phonegap-SQLitePlugin
-
-## Using with SQLCipher
-
-- for Android version: [this blog posting](http://brodyspark.blogspot.com/2012/12/using-sqlcipher-for-android-with.html) & [enhancements to SQLCipher db classes for Android](http://brodyspark.blogspot.com/2012/12/enhancements-to-sqlcipher-db-classes.html)
-- for iOS version: [this posting](http://brodyspark.blogspot.com/2012/12/integrating-sqlcipher-with.html)
-
-**NOTE:** This documentation is out-of-date and to be replaced very soon.
+- Original version for iOS (with a different API): https://github.com/davibe/Phonegap-SQLitePlugin
 
 # Usage
 
@@ -93,9 +63,14 @@ The idea is to emulate the HTML5 SQL API as closely as possible. The only major
 ## Opening a database
 
 There are two options to open a database:
-- Recommended: `var db = window.sqlitePlugin.openDatabase({name: "my.db"});`
+- Recommended: `var db = window.sqlitePlugin.openDatabase({name: "my.db", location: 1});`
 - Classical: `var db = window.sqlitePlugin.openDatabase("myDatabase.db", "1.0", "Demo", -1);`
 
+The new `location` option is used to select the database subdirectory location (iOS *only*) with the following choices:
+- `0` (default): `Documents` - will be visible to iTunes and backed up by iCloud
+- `1`: `Library` - backed up by iCloud, *NOT* visible to iTunes
+- `2`: `Library/LocalDatabase` - *NOT* visible to iTunes and *NOT* backed up by iCloud
+
 **IMPORTANT:** Please wait for the "deviceready" event, as in the following example:
 
 ```js
@@ -111,6 +86,19 @@ function onDeviceReady() {
 
 **NOTE:** The database file name should include the extension, if desired.
 
+### Pre-populated database
+
+For Android & iOS (*only*): put the database file in the `www` directory and open the database like:
+
+```js
+ var db = window.sqlitePlugin.openDatabase({name: "my.db", createFromLocation: 1});
+```
+
+**IMPORTANT NOTES:**
+
+- Put the pre-populated database file in the `www` subdirectory. This should work well with using the Cordova CLI to support both Android & iOS versions.
+- The pre-populated database file name must match **exactly** the file name given in `openDatabase`. The automatic extension has been completely eliminated.
+
 ## Background processing
 
 The threading model depends on which version is used:
@@ -193,9 +181,11 @@ This case will also works with Safari (WebKit), assuming you replace window.sqli
 ## Delete a database
 
 ```js
-window.sqlitePlugin.deleteDatabase("my.db", successcb, errorcb);
+window.sqlitePlugin.deleteDatabase({name: "my.db", location: 1}, successcb, errorcb);
 ```
 
+`location` as described above for `openDatabase` (iOS *only*)
+
 # Installing
 
 **NOTE:** This plugin is now prepared to be installed using the `cordova` tool.
@@ -381,17 +371,17 @@ If you have any questions about the plugin please post it to the [Cordova-SQLite
 
 **Low priority:** issues with the API or application integration will be given lower priority until the Cordova 3.0 integration is finished for Windows Phone 8. Pull requests are very welcome for these kinds of issues.
 
-## Professional support
+# Unit tests
 
-Available for integration with SQLCipher.
+Unit testing is done in `test-www/`.
 
-# Unit test(s)
-
-Unit testing is done in `test-www/`. To run the tests from *nix shell, simply do either:
+## running tests from shell
 
+To run the tests from \*nix shell, simply do either:
+
  ./bin/test.sh ios
 
-or in Android:
+or for Android:
 
  ./bin/test.sh android
 

SQLitePlugin.coffee.md

@@ -1,24 +1,24 @@
 # SQLitePlugin in Markdown (litcoffee)
 
-New coffee compiler can compile this directly into Javascript
+#### Use coffee compiler to compile this directly into Javascript
 
-License for common Javascript: MIT or Apache
+#### License for common script: MIT or Apache
 
-## Top-level SQLitePlugin objects
+# Top-level SQLitePlugin objects
 
-### root window object:
+## root window object:
 
  root = @
 
-### constant(s):
+## constant(s):
 
  READ_ONLY_REGEX = /^\s*(?:drop|delete|insert|update|create)\s/i
 
-### global(s):
+## global(s):
 
  txLocks = {}
 
-### utility function(s):
+## utility functions:
 
  nextTick = window.setImmediate || (fun) ->
  window.setTimeout(fun, 0)
@@ -40,7 +40,7 @@ License for common Javascript: MIT or Apache
  else
  return fun.call this, []
 
-### SQLitePlugin db-connection
+## SQLitePlugin db-connection
 
 #### SQLitePlugin object is defined by a constructor function and prototype member functions:
 
@@ -128,6 +128,10 @@ License for common Javascript: MIT or Apache
  #console.log "SQLitePlugin.prototype.close"
 
  if @dbname of @openDBs
+ if txLocks[@dbname] && txLocks[@dbname].inProgress
+ error(new Error('database cannot be closed while a transaction is in progress'))
+ return
+
  delete @openDBs[@dbname]
 
  cordova.exec success, error, "SQLitePlugin", "close", [ { path: @dbname } ]
@@ -145,7 +149,7 @@ License for common Javascript: MIT or Apache
  @addTransaction new SQLitePluginTransaction(this, myfn, null, null, false, false)
  return
 
-### SQLitePluginTransaction object for batching:
+## SQLitePluginTransaction object for batching:
 
  ###
  Transaction batching object:
@@ -281,8 +285,6 @@ License for common Javascript: MIT or Apache
 
  tropts.push
  qid: qid
- # for ios version:
- query: [request.sql].concat(request.params)
  sql: request.sql
  params: request.params
 
@@ -360,7 +362,9 @@ License for common Javascript: MIT or Apache
 
  return
 
-### SQLite plugin object factory:
+## SQLite plugin object factory:
+
+ dblocations = [ "docs", "libs", "nosync" ]
 
  SQLiteFactory =
  ###
@@ -391,13 +395,33 @@ License for common Javascript: MIT or Apache
  okcb = args[1]
  if args.length > 2 then errorcb = args[2]
 
+ dblocation = if !!openargs.location then dblocations[openargs.location] else null
+ openargs.dblocation = dblocation || dblocations[0]
+
+ if !!openargs.createFromLocation and openargs.createFromLocation == 1
+ openargs.createFromResource = "1"
+
  new SQLitePlugin openargs, okcb, errorcb
 
- deleteDb: (databaseName, success, error) ->
- delete SQLitePlugin::openDBs[databaseName]
- cordova.exec success, error, "SQLitePlugin", "delete", [{ path: databaseName }]
+ deleteDb: (first, success, error) ->
+ args = {}
+
+ if first.constructor == String
+ #console.log "delete db name: #{first}"
+ args.path = first
+ args.dblocation = dblocations[0]
+
+ else
+ #console.log "delete db args: #{JSON.stringify first}"
+ if !(first and first['name']) then throw new Error("Please specify db name")
+ args.path = first.name
+ dblocation = if !!first.location then dblocations[first.location] else null
+ args.dblocation = dblocation || dblocations[0]
+
+ delete SQLitePlugin::openDBs[args.path]
+ cordova.exec success, error, "SQLitePlugin", "delete", [ args ]
 
-### Exported API:
+## Exported API:
 
  root.sqlitePlugin =
  sqliteFeatures:

bin/test.sh

@@ -49,6 +49,6 @@ cp -r ../src ../plugin.xml ../www ../.plugin
 
 # update the plugin, run the test app
 cordova platform add $platform
-cordova plugin rm com.phonegap.plugins.sqlite
+cordova plugin rm com.brodysoft.sqlitePlugin
 cordova plugin add ../.plugin
 cordova run $platform