Class Index

Classes


v1.2.1

DB

This is the root database object accessible either by window.db or more simply db . This object is the primary access to the SequelSphere database, and contains the following helpful properties, methods, and attributes:

Summary
Constructor Attributes Constructor Name and Description
DB ()
This object is the single access point to the database.
Field Summary
Field Attributes Field Name and Description
The DBCatalog of tables used to create, alter, and drop tables.
The manager of "change trackers" which are useful tools for recording and reporting changes to data in tables.
<static>
This signifies that a table's persistence scope should be the same as the catalog's persistence scope.
<static>
This signifies that a catalog or table should be stored in local storage on the browser to allow persistence across brower restarts.
<static>
This signifies that a catalog's or table's persistence scope should be in memory, and not persist across browser tabs or restarts.
<static>
This signifies that a catalog's or table's persistence scope should be in Session, persisting across browser tabs, but not across brower restarts.
Method Summary
Method Attributes Method Name and Description
addTableProvider (tableProvider)
This adds a custom TableProvider to the SequelSphereDB engine that can provide additional non-SequelSphere tables to be used in SQL queries (awesomeness).
commit (notifyObj)
Performs a transactional commit of the current state of the database.
query (sql)
Performs a SELECT statement processing the query completely before returning all the results formatted in an array of rows and columns.
Performs a SELECT statement returning a cursor.
Performs a SELECT statement processing the query completely before returning all the results formatted in an array of Objects.
Performs a SELECT statement returning the first result row of a query with the values in an array, or NULL if no rows are returned from the query.
Performs a SELECT statement returning the first result row of a query with the values in an object, or NULL if no rows are returned from the query.
Performs a SELECT statement returning a scalar value (the first row/column value), or NULL if no rows are returned from the query.
removeTableProvider (tableProvider)
This removes a previously added TableProvider from the SequelSphereDB engine.
rollback (notifyObj)
Performs a transactional rollback to the state of the database at the time of the last commit() or database initialization.
Event Summary
Event Attributes Event Name and Description
Notifies its listeners that the database has been initialized and is ready to be used.
Detail
DB ()
This object is the single access point to the database.
Field Detail
catalog
The DBCatalog of tables used to create, alter, and drop tables. This is the primary point of entry for creating and manipulating database tables. Please note that database catalog changes should only occur after the database has been initialized and is ready (see DB#onready).
See:
DBCatalog
DB#onready

changeTrackers
The manager of "change trackers" which are useful tools for recording and reporting changes to data in tables.
See:
DBChangeTrackerManager
DBChangeTracker

<static> DB. SCOPE_DEFAULT
This signifies that a table's persistence scope should be the same as the catalog's persistence scope. This is the initial scope for a table, and is not a valid scope for the catalog.
See:
DBTable#setPersistenceScope

<static> DB. SCOPE_LOCAL
This signifies that a catalog or table should be stored in local storage on the browser to allow persistence across brower restarts.
See:
DBCatalog#setPersistenceScope
DBTable#setPersistenceScope

<static> DB. SCOPE_PAGE
This signifies that a catalog's or table's persistence scope should be in memory, and not persist across browser tabs or restarts. This means that the catalog will only exist for a single page load.
See:
DBCatalog#setPersistenceScope
DBTable#setPersistenceScope

<static> DB. SCOPE_SESSION
This signifies that a catalog's or table's persistence scope should be in Session, persisting across browser tabs, but not across brower restarts. Please note that the "Session" behavior is dictated by each browser's implementation of the sessionStorage API.
See:
DBCatalog#setPersistenceScope
DBTable#setPersistenceScope
Method Detail
addTableProvider (tableProvider)
This adds a custom TableProvider to the SequelSphereDB engine that can provide additional non-SequelSphere tables to be used in SQL queries (awesomeness).
Parameters:
{object} tableProvider
An object implementing the TableProvider interface.
See:
TableProvider
IterableTable

commit (notifyObj)
Performs a transactional commit of the current state of the database. When this occurs, the current catalog and tables are also saved to their specified persistence scope.

This method will commit all changes to the database that take part in the transaction. This includes creating, dropping, and modifying tables; inserting, updating, and deleting rows, and even changes to catalog settings.

This method attempts to perform the commit synchronously, but if the underlying persistence mechanism does not allow it, then the commit will work asynchronously. In either case, it will notify the provided object of success or error via onsuccess() and onerror(errStr) callbacks.

The following is an example of it's use:

	db.commit({
		onsuccess: function() {
			window.alert("commit() succeeded!");
		},
		onerror: function(errStr) {
			window.alert("commit() failed with the following message: " + errStr);
		}
	});
	
Parameters:
{object} notifyObj
A notification object containing onsuccess() and onerror(errStr) callbacks.
See:
DB#rollback
DBCatalog#setPersistenceScope

{ DBQueryResult } query (sql)
Performs a SELECT statement processing the query completely before returning all the results formatted in an array of rows and columns.

Here is some sample code utilizing the query() method:

	    var res = db.query(sql);
	    //    res has the following attributes:
	    //        - columnNames [] of Column Names
	    //        - data        [][] of results (row/col)
	    for (var c = 0; c < res.columnNames.length; ++c) {
	        var colName = res.columnNames[c];
	        // use column name here
	    }
	    for (var row = 0; row < res.data.length; ++row) {
	        for (var col = 0; col < res.columnNames.length; ++col) {
	            var cellVal = res.data[row][col];
	            // use data here
	        }
	    }
	
Parameters:
{string} sql
A SQL query to execute
Throws:
{ Exception }
If there is an error in the SQL.
Returns:
{ DBQueryResult } a DBQueryResult object containing the results of the query.
See:
DBQueryResult#data

{ DBCursor } queryCursor (sql)
Performs a SELECT statement returning a cursor.

This method will return quickly, only performing the steps necessary to begin iterating through the result set. Subsequent calls to the DBCursor#next method will then iterate through the rows in the cursor.

Here is some sample code utilizing the queryCursor() method:

	    // sql is the SQL to be executed.
	    var cursor = db.queryCursor(sql);
	    while (cursor.next()) {
	        for (var col = 0; col < cursor.getColumnCount(); ++col) {
	            var cellVal = cursor.getValue(col);
	            // use data here
	        }
	    }
	
Parameters:
{string} sql
A SQL query to execute
Throws:
{ Exception }
If there is an error in the SQL.
Returns:
{ DBCursor } a DBCursor object containing the results of the query.

{ DBQueryResult } queryObjects (sql)
Performs a SELECT statement processing the query completely before returning all the results formatted in an array of Objects.

Here is some sample code utilizing the queryObjects() method:

	    var res = db.queryObjects(sql);
	    //    res has the following attributes:
	    //        - columnNames [] of Column Names
	    //        - data        [] of result objects (row)
	    for (var c = 0; c < res.columnNames.length; ++c) {
	        var colName = res.columnNames[c];
	        // use column name here
	    }
	    for (var row = 0; row < res.data.length; ++row) {
	        var rowObj = res.data[row];
	        var id = rowObj['ID'];  // Returns column 'ID'
	        var name = rowObj.NAME;  // Returns column 'NAME'
	        // use data here
	    }
	
Parameters:
{string} sql
A SQL query to execute
Throws:
{ Exception }
If there is an error in the SQL.
Returns:
{ DBQueryResult } a DBQueryResult object containing the results of the query.
See:
DBQueryResult#data

{*[]} queryRow (sql)
Performs a SELECT statement returning the first result row of a query with the values in an array, or NULL if no rows are returned from the query.

Here is some sample code utilizing the queryRow() method:

		var arr = db.queryRow("select id, name from empl where id = 1");
		var id = arr[0];
		var name = arr[1];
	
Parameters:
{string} sql
A SQL query to execute
Throws:
{ Exception }
If there is an error in the SQL.
Returns:
{*[]} The first result row of the query, or 'null' if no rows are returned.

{object} queryRowObject (sql)
Performs a SELECT statement returning the first result row of a query with the values in an object, or NULL if no rows are returned from the query.

Here is some sample code utilizing the queryRowObject() method:

		var rowObj = db.queryRowObject("select id, name from empl where id = 1");
		var id = rowObj['ID'];
		var name = rowObj.NAME;
	
Parameters:
{string} sql
A SQL query to execute
Throws:
{ Exception }
If there is an error in the SQL.
Returns:
{object} The first row of a query as an object with the values indexed as attributes, or 'null' if no rows are returned.

{*} queryValue (sql)
Performs a SELECT statement returning a scalar value (the first row/column value), or NULL if no rows are returned from the query.

Here is some sample code utilizing the queryValue() method:

	    var name = db.queryValue("select name from empl where id = 1");
	
Parameters:
{string} sql
A SQL query to execute
Throws:
{ Exception }
If there is an error in the SQL.
Returns:
{*} The first row/column value, or 'null' if no rows are returned.

removeTableProvider (tableProvider)
This removes a previously added TableProvider from the SequelSphereDB engine.
Parameters:
{object} tableProvider
A TableProvider that was previously added to the database.
See:
DB#addTableProvider
TableProvider

rollback (notifyObj)
Performs a transactional rollback to the state of the database at the time of the last commit() or database initialization.

This method will rollback all changes to the database that take part in the transaction. This includes creating, dropping, and modifying tables; inserting, updating, and deleting rows, and even changes to catalog settings.

PLEASE NOTE: If you do not perform a DB#commit after initially creating and populating tables in an empty database, a rollback() will revert the database back to its empty state.

This method attempts to perform the rollback synchronously, but if the underlying persistence mechanism does not allow it, then the commit will work asynchronously. In either case, it will notify the provided object of success or error via onsuccess() and onerror(errStr) callbacks.

The following is an example of it's use:

	db.rollback({
		onsuccess: function() {
			window.alert("rollback() succeeded!");
		},
		onerror: function(errStr) {
			window.alert("rollback() failed with the following message: " + errStr);
		}
	});
	
Parameters:
{object} notifyObj
A notification object containing onsuccess() and onerror(errStr) callbacks.
See:
DB#commit
Event Detail
onready ()
Notifies its listeners that the database has been initialized and is ready to be used. Every listener passed to this event is guaranteed to be called one time only. This includes listeners added to the event after it is initially raised.

This event fires after the database engine loads the catalog from the local storage mechanism (if one exists). All calls to the database and catalog should only occur after this event has been raised.

Here is some sample code utilizing the onready event:

		db.onready(function() {
			//	Check to see if the tables already exist
			if (db.catalog.getTable("apptab") == null) {
				myCreateTablesFunction();
			}
			myDoStuffFunction();
		});
	

This event can also be called 'onReady'.


©2012 Sequel Sphere, LLC.