Class Index

Classes


v1.2.1

DBChangeTracker

This class provides the ability to track and report changes to data in tables. The data changes (Insert / Update / Delete rows) are reported in a "transaction log" format useful for synchronization purposes. The change tracker can even work when offline and store the data changes to be retrieved across browser restarts. Yes, it is very cool.

To create a "change tracker" for tracking changes on three tables, perform the following:

var myTracker = db.changeTrackers.create("MyTracker", ["tab_one", "tab_two", "tab_three"]);

From that point on, data changes made to the three tables are automatically recorded. Keeping a reference to the change tracker is not necessary, as it can be retrieved later through the DBChangeTrackerManager#get (name) method.

Usage Notes

Please consider the following important notes when using a change tracker:

Example Usage

The following script provides an example usage of a change tracker:

     //  Create a tracker for 3 tables and automatically begin recording changes.
 db.changeTrackers.create("MyTracker", ["hobbits", "weapons", "locations"]);

     // ...  Perform INSERT, UPDATE, and DELETE statements to be tracked

     // temporarily pause the tracking
 db.changeTrackers.get("MyTracker").endTracking();

     // ...  Perform changes to tables that are NOT recorded.

     // resume the tracking
 db.changeTrackers.get("MyTracker").beginTracking();

     // ...  Perform more INSERT, UPDATE, and DELETE statements to be tracked

     //  Now it's time to get our changes
 var changes = db.changeTrackers.get("MyTracker").getChangedRows();

     //  Alternatively, let's get our changes as objects
 var changeObjects = db.changeTrackers.get("MyTracker").getChangedRowObjects();

     // Now let's synchronize these change up to our server...
     // ... your synchronization code here ...

     //  Let's reset the tracker by clearing out the changes
 db.changeTrackers.get("MyTracker").clearChanges();

     //  Finally, let's drop our tracker, since it is no longer needed.
 db.changeTrackers.drop("MyTracker");
 

Example Change Reports

In the above script, the two methods to retrieve the tracked changes would return objects that look like the following:

 var changes = db.changeTrackers.get("MyTracker").getChangedRows();

     //  'changes' is a JSON array that looks like:
 [
     { seqNbr: 0, action: 'I', table: 'HOBBITS',   row: [ 4, 'Frodo', 'Baggins' ] },
     { seqNbr: 1, action: 'U', table: 'HOBBITS',   row: [ 4, 'Samwise', 'Gamgee' ] },
     { seqNbr: 2, action: 'U', table: 'WEAPONS',   row: [ 12, 'Sting', 32 ] },
     { seqNbr: 3, action: 'D', table: 'HOBBITS',   row: [ 4, 'Samwise', 'Gamgee' ] },
     { seqNbr: 4, action: 'I', table: 'WEAPONS',   row: [ 15, 'Elven Bow', 5 ] },
     { seqNbr: 5, action: 'U', table: 'LOCATIONS', row: [ 2, 'Shire', 'Middle Earth' ] }
 ]

 var changeObjects = db.changeTrackers.get("MyTracker").getChangedRowObjects();

     //  'changeObjects' is a JSON array that looks like:
 [
     { seqNbr: 0, action: 'I', table: 'HOBBITS',   row: { id: 4, first_name: 'Frodo', last_name: 'Baggins' } },
     { seqNbr: 1, action: 'U', table: 'HOBBITS',   row: { id: 4, first_name: 'Samwise', last_name: 'Gamgee' } },
     { seqNbr: 2, action: 'U', table: 'WEAPONS',   row: { id: 12, name: 'Sting', damage: 32 } },
     { seqNbr: 3, action: 'D', table: 'HOBBITS',   row: { id: 4, first_name: 'Samwise', last_name: 'Gamgee' } },
     { seqNbr: 4, action: 'I', table: 'WEAPONS',   row: { id: 15, name: 'Elven Bow', damage: 5 } },
     { seqNbr: 5, action: 'U', table: 'LOCATIONS', row: { id: 2, name: 'Shire', world: 'Middle Earth' } }
 ]
	

Summary
Constructor Attributes Constructor Name and Description
This class provides the ability to track and report changes to data in tables.
Field Summary
Field Attributes Field Name and Description
The name of this Change Tracker.
Method Summary
Method Attributes Method Name and Description
Begin (resume) tracking changes to the tables after the tracking was ended (paused) by a call to #endTracking () .
Clears all changes from the DBChangeTracker .
End (pause) tracking changes to the tables.
Retrieves the tracked changes as a "Transaction Log" in sequence order with the row data represented as an object with values indexed by column name.
getChangedRows (tableNames)
Retrieves the tracked changes as a "Transaction Log" in sequence order with the row data represented as an array of values in column order.
Gets the current "persistence scope" of the change tracker.
Gets the names of the tables being tracked by this Change Tracker.
Returns whether or not the change tracker is currently tracking changes.
setPersistenceScope (newPersistenceScope)
Sets the "persistence scope" of the change tracker.
Detail
DBChangeTracker ()
This class provides the ability to track and report changes to data in tables.
See:
DB#changeTrackers
DBChangeTrackerManager
Field Detail
{string} name
The name of this Change Tracker.
Method Detail
beginTracking ()
Begin (resume) tracking changes to the tables after the tracking was ended (paused) by a call to #endTracking () .

The following is an example of how to pause and resume a change tracker:

	// First, retrieve the tracker.
	var myTracker = db.changeTrackers.get("My_Empl_Tracker");

	myTracker.endTracking(); // pause the tracking

	// ... Perform untracked changes to the tables here ...

	myTracker.beginTracking(); // resume the tracking
	
See:
DBChangeTracker#endTracking
DBChangeTracker#isTracking

clearChanges ()
Clears all changes from the DBChangeTracker .

The following is an example of how to clear the changes from a change tracker:

	// First, retrieve the tracker.
	var myTracker = db.changeTrackers.get("My_Empl_Tracker");
	myTracker.clearChanges(); // get rid of all the changes.
	

This method participates in a transaction, so a DB#rollback () will "recreate" the changes within the change tracker. DB#commit () will finalize the clearing of all the changes.


endTracking ()
End (pause) tracking changes to the tables. The tracking can be resumed with a call to #beginTracking () .

The following is an example of how to pause and resume a change tracker:

	// First, retrieve the tracker.
	var myTracker = db.changeTrackers.get("My_Empl_Tracker");

	myTracker.endTracking(); // pause the tracking

	// ... Perform untracked changes to the tables here ...

	myTracker.beginTracking(); // resume the tracking
	
See:
DBChangeTracker#beginTracking
DBChangeTracker#isTracking

{[]} getChangedRowObjects (tableNames)
Retrieves the tracked changes as a "Transaction Log" in sequence order with the row data represented as an object with values indexed by column name. The returned "transaction log" is an array of objects containing the following properties:

Example:

The following is an example of how to retrieve the changes from a change tracker:

 var changeObjects = db.changeTrackers.get("MyTracker").getChangedRowObjects();

     //  'changeObjects' is a JSON array that looks like:
 [
     { seqNbr: 0, action: 'I', table: 'HOBBITS',   row: { id: 4, first_name: 'Frodo', last_name: 'Baggins' } },
     { seqNbr: 1, action: 'U', table: 'HOBBITS',   row: { id: 4, first_name: 'Samwise', last_name: 'Gamgee' } },
     { seqNbr: 2, action: 'U', table: 'WEAPONS',   row: { id: 12, name: 'Sting', damage: 32 } },
     { seqNbr: 3, action: 'D', table: 'HOBBITS',   row: { id: 4, first_name: 'Samwise', last_name: 'Gamgee' } },
     { seqNbr: 4, action: 'I', table: 'WEAPONS',   row: { id: 15, name: 'Elven Bow', damage: 5 } },
     { seqNbr: 5, action: 'U', table: 'LOCATIONS', row: { id: 2, name: 'Shire', world: 'Middle Earth' } }
 ]
	

Implementation Notes:

Parameters:
{string | string[]} tableNames
<OPTIONAL> The names of the table(s) whose changes should be returned. If ommitted, changes to all tables are returned.
Returns:
{[]} An array of objects detailing the changes in sequence order.
See:
#getChangeRows

{[]} getChangedRows (tableNames)
Retrieves the tracked changes as a "Transaction Log" in sequence order with the row data represented as an array of values in column order. The returned "transaction log" is an array of objects containing the following properties:

Example:

The following is an example of how to retrieve the changes from a change tracker:

 var changes = db.changeTrackers.get("MyTracker").getChangedRows();

     //  'changes' is a JSON array that looks like:
 [
     { seqNbr: 0, action: 'I', table: 'HOBBITS',   row: [ 4, 'Frodo', 'Baggins' ] },
     { seqNbr: 1, action: 'U', table: 'HOBBITS',   row: [ 4, 'Samwise', 'Gamgee' ] },
     { seqNbr: 2, action: 'U', table: 'WEAPONS',   row: [ 12, 'Sting', 32 ] },
     { seqNbr: 3, action: 'D', table: 'HOBBITS',   row: [ 4, 'Samwise', 'Gamgee' ] },
     { seqNbr: 4, action: 'I', table: 'WEAPONS',   row: [ 15, 'Elven Bow', 5 ] },
     { seqNbr: 5, action: 'U', table: 'LOCATIONS', row: [ 2, 'Shire', 'Middle Earth' ] }
 ]
	

Implementation Notes:

Parameters:
{string | string[]} tableNames
<OPTIONAL> The names of the table(s) whose changes should be returned. If ommitted, changes to all tables are returned.
Returns:
{[]} An array of objects detailing the changes in sequence order.
See:
#getChangeRowObjects

{const} getPersistenceScope ()
Gets the current "persistence scope" of the change tracker. The scope specifies whether the changes recorded by the tracker will be stored in memory, in Session, or in a local storage mechanism.
Returns:
{const} The persistence scope of the change tracker.
See:
DBChangeTracker#setPersistenceScope
DBCatalog#isPersistenceScopeAvailable

{string[]} getTableNames ()
Gets the names of the tables being tracked by this Change Tracker. This is purely for inspection purposes.
Returns:
{string[]} An Array of string values specifying the names of the table(s) being tracked.

isTracking ()
Returns whether or not the change tracker is currently tracking changes.

The following is an example of how to pause and resume a change tracker:

 // First, create the tracker.
 var myTracker = db.changeTrackers.create("My_Empl_Tracker", "EMPL");

 if (myTracker.isTracking()) { // isTracking() returns 'true'
     myTracker.endTracking(); // pause the tracking

     if (!myTracker.isTracking()) // isTracking() returns 'false'
         myTracker.beginTracking(); // resume the tracking
 }
	
See:
DBChangeTracker#beginTracking
DBChangeTracker#endTracking

setPersistenceScope (newPersistenceScope)
Sets the "persistence scope" of the change tracker. This specifies whether the changes recorded by the tracker will be stored in memory, in Session, or in a local storage mechanism.

This method takes part in a transaction, so a DB#commit is required to finalize it, and a DB#rollback will revert the change.

Parameters:
{const} newPersistenceScope
The new Persistence Scope
See:
DBChangeTracker#getPersistenceScope
DBCatalog#isPersistenceScopeAvailable
DB#commit

©2012 Sequel Sphere, LLC.