Class Index

Classes


v1.2.1

IterableTable

This is an "Interface" that can be implemented to provide a user-defined (Non-SequelSphere) table for the SequelSphereDB engine to include in SQL queries. Objects implementing this Interface should be returned from a custom TableProvider 's TableProvider#getIterableTable method. Please see the documentation for TableProvider for more information on how this works.

To implement this interface, an object must have the following methods:

The first method, #getColumnNames (), returns the names of the columns for the data as an array of strings. Please note that these column names will be treated in a case-insensitive manner, since SQL is case insensitive. As such, any columns with the same case-insensitive name will be resolved to the last matching column in the table.

The last three methods of this interface describe a very simple "Iteration" pattern to return the data. In this pattern of "Iteration", the object should be initialized to a state BEFORE the first row of data. A call to the #next () method should advance the iterator to the first row of data, and return ' true ' if that row exists. Subsequent calls to the #next () method should continue to advance the iterator to the next row, returning ' true ' for as long as there are rows of data to be returned from the table. Once the iterator has been advanced past the last row of data, the #next () method should return ' false '. A call to #reset () should reset the iterator back to BEFORE the first row of data.

To illustrate, this pattern should support the following method for retrieving the first 2 columns of data from the table:

	//  First, retrieve the "IterableTable":
	var iterableTable = myTableProvider.getIterableTable(tableName);

	//  Next, retrieve the column names:
	var colNames = iterableTable.getColumnNames();

	//  Now, iterate through the table retrieving the first two columns of data.
	while (iterableTable.next()) {
	    var col1Value = iterableTable.getValue(colNames[0]);
	    var col2Value = iterableTable.getValue(colNames[1]);
	}
	

At any time during the iteration process, a call to #reset () should reset the iterator to BEFORE the first row of data, thereby allowing the table to be iterated again:

	//  Reset the iterableTable back to before the first row.
	iterableTable.reset();

	//  Now, iterate through the table retrieving the first two columns of data.
	while (iterableTable.next()) {
	    var col1Value = iterableTable.getValue(colNames[0]);
	    var col2Value = iterableTable.getValue(colNames[1]);
	}
	

Sample Implementation

The following is a simple implementation of the IterableTable Interface for a table with two columns, 'id' and 'name':

	//  Create an object for my data implementing the IterableTable interface:
	function MyIterableTable() {
	    var rowIdx = -1;                   // Keep track of the row
	    var data = [                       // 3 rows, 2 columns of data
	        { id: 1, name: 'Bob'   },
	        { id: 2, name: 'Frank' },
	        { id: 3, name: 'Mary'  }
	    ];
	    this.getColumnNames = function() {
	        return ['id', 'name'];    // return the column names
	    },
	    this.reset = function() {
	        rowIdx = -1;         // Reset the row index prior to first row.
	    },
	    this.next = function() {
	        ++rowIdx;            // Advance the row and return if there is more.
	        return (rowIdx < data.length);
	    },
	    this.getValue = function(colName) { // Return the requested value.
	        return data[rowIdx][colName];
	    }
	}
	

The Above IterableTable object could be called 'USERS', and provided to the SequelSphereDB Engine as follows:

	var myTableProvider = {
	    getIterableTable: function(tabName) {
	        if (tabName == "USERS")
	            return new MyIterableTable();
	        return null;
	    }
	};
	db.addTableProvider(myTableProvider);
	

Implementation Notes

Summary
Constructor Attributes Constructor Name and Description
This "Interface" should be implemented to provide a user-defined table for the SequelSphereDB engine to include in SQL queries.
Method Summary
Method Attributes Method Name and Description
This method returns the names of the columns corresponding to the IterableTable.
getValue (columnName)
This method is called to retrieve the value for a column for the current row in the iteration.
This method should advance the iterator to the next row, returning whether or not another row exists.
This method resets the Iteration state to be prior to the first row of data.
Detail
IterableTable ()
This "Interface" should be implemented to provide a user-defined table for the SequelSphereDB engine to include in SQL queries.
See:
TableProvider
TableProvider#getIterableTable
Method Detail
{string[]} getColumnNames ()
This method returns the names of the columns corresponding to the IterableTable. Please note the following when implementing:
Returns:
{string[]} An array of strings specifying the names of the columns.

{object} getValue (columnName)
This method is called to retrieve the value for a column for the current row in the iteration. Please note the following when implementing:
Parameters:
{string} columnName
The name of the column whose value is being retrieved.
Returns:
{object} The value of the requested column at the current row, or null if there is no value.

{boolean} next ()
This method should advance the iterator to the next row, returning whether or not another row exists.
Returns:
{boolean} Whether or not another row exists.

reset ()
This method resets the Iteration state to be prior to the first row of data. Please note the following when implementing:

©2012 Sequel Sphere, LLC.