Class Impel.Criteria

A utility class for holding criteria information for an SQL query.

Class Summary
Constructor Attributes	Constructor Name and Description
	Impel.Criteria(options, events) A utility class for holding criteria information for an SQL query.

Method Summary
Method Attributes	Method Name and Description
<static>	Impel.Criteria.add(peer_columnOrCrit, value, comparison) Add a Impel.Criterion to this Impel.Criteria object.
<static>	Impel.Criteria.addAnd(peer_columnOrCrit, value, comparison) Add a Impel.Criterion to this Impel.Criteria object.
<static>	Impel.Criteria.addAscendingOrderByColumn(peer_column) Sort the results of any SQL query constructed from this Impel.Criteria by the column specified in ascending order
<static>	Impel.Criteria.addCriterion(crit, conjunction) Add a Impel.Criterion to this Impel.Criteria object.
<static>	Impel.Criteria.addDescendingOrderByColumn(peer_column) Sort the results of any SQL query constructed from this Impel.Criteria by the column specified in descending order
<static>	Impel.Criteria.addGroupByColumn(peer_column) Group the results of any SQL query constructed from this Impel.Criteria by the column specified
<static>	Impel.Criteria.addJoin(left, right, operator) Add a JOIN clause to this Impel.Criteria.
<static>	Impel.Criteria.addOr(peer_columnOrCrit, value, comparison) Add a Impel.Criterion to this Impel.Criteria object.
<static>	Impel.Criteria.addSelectColumn(peer_column) Add a column to the SELECT clause of the SQL statement that will be executed against the database.
<static>	Impel.Criteria.addTable(table) Add a table to the list of tables that will be used in any SQL statement constructed from this Impel.Criteria.
<static>	Impel.Criteria.getDeleteSQL() Retrieve a complete SQL DELETE statement constructed from this Impel.Criteria.
<static>	Impel.Criteria.getInsertSQL() Retrieve a complete SQL Insert statement constructed from this Impel.Criteria.
<static>	Impel.Criteria.getLeftJoinClauses() Retrieve an Object representing the LEFT JOIN clauses that have been added to this Impel.Criteria.
<static>	Impel.Criteria.getNewCriterion(peer_column, value, comparison) Retrieve a new Impel.Criterion object that is not automatically added to this Impel.Criteria object.
<static>	Impel.Criteria.getSelectColumns() Retrieve a list of columns that will be used to make up the SELECT
<static>	Impel.Criteria.getSelectModifiers() Retrieve any modifiers that have been added to the SELECT clause of the Impel.Criteria.
<static>	Impel.Criteria.getSelectSQL() Retrieve a complete SQL SELECT statment constructed from this Impel.Criteria.
<static>	Impel.Criteria.getTableNames() Retrive a list of all the tables that will be used in any SQL statement constructed from this Impel.Criteria.
<static>	Impel.Criteria.getUpdateSQL(constrainCrit) Retrieve a complet SQL Update statement constructed from this Impel.Criteria.
<static>	Impel.Criteria.getValues() Retrieve all values that have been added to this Impel.Criteria in the order they were added.
<static>	Impel.Criteria.getWhereClause() Retrieve only the WHERE clauses portion of an SQL statement constructed from this Impel.Criteria.
<static>	Impel.Criteria.hasSelectColumns() Does this Impel.Criteria contain any columns that will be used in the SELECT clause of an SQL statment?
<static>	Impel.Criteria.leftJoinsHas(peer_column) Does this Impel.Criteria contain a LEFT JOIN clause for the given peer_column.
<static>	Impel.Criteria.setDistinct() Add the DISTINCT modifier to the SELECT clause of any SQL statement constructed from this Impel.Criteria.
<static>	Impel.Criteria.setLimit(limit) Set a limit on the number of results.

Class Detail

Impel.Criteria(options, events)

Parameters:
{Object} options: Options to bind to this Impel.Criteria object. Currently no configurable Options are supported by this class.
{Object} events: Events to bind to to this Impel.Criteria object. Currently no Events are fired by this class

Method Detail

<static> Impel.Criteria.add(peer_columnOrCrit, value, comparison)

Add a Impel.Criterion to this Impel.Criteria object.

Potential Issue: does add allow the same column to be added more than once?

Parameters:
{Impel.Criterion|String} peer_columnOrCrit
{String} value
{String} comparison Optional, Default: Impel.CritConstants.EQUAL

See:: Impel.Criterion

<static> Impel.Criteria.addAnd(peer_columnOrCrit, value, comparison)

Add a Impel.Criterion to this Impel.Criteria object. If this Impel.Criteria contains other Impel.Criterion the Impel.Criterion will be added with an 'AND' conjunction

Parameters:
{Impel.Criterion|String} peer_columnOrCrit
{String} value
{String} comparison Optional, Default: Impel.CritConstants.EQUAL

See:: Impel.Criteria#add

<static> Impel.Criteria.addAscendingOrderByColumn(peer_column)

Sort the results of any SQL query constructed from this Impel.Criteria by the column specified in ascending order

var c = new Impel.Criteria();
    c.addAscendingOrderByColumn("PlayePeer::zipcode");

Parameters:
{String} peer_column

See:: Impel.Criteria#addDescendingOrderByColumn

<static> Impel.Criteria.addCriterion(crit, conjunction)

Add a Impel.Criterion to this Impel.Criteria object. If this Impel.Criteria contains other Impel.Criterion the Impel.Criterion will be added with the passed in conjunction

Parameters:
{Impel.Criterion} crit
{String} conjunction Optional, Default: Impel.CritConstants.AND

See:: Impel.Criterion

<static> Impel.Criteria.addDescendingOrderByColumn(peer_column)

Sort the results of any SQL query constructed from this Impel.Criteria by the column specified in descending order

var c = new Impel.Criteria();
    c.addDescendingOrderByColumn("PlayerPeer::zipcode");

Parameters:
{String} peer_column

See:: Impel.Criteria#addAscendingOrderByColumn

<static> Impel.Criteria.addGroupByColumn(peer_column)

Group the results of any SQL query constructed from this Impel.Criteria by the column specified

Parameters:
{String} peer_column

<static> Impel.Criteria.addJoin(left, right, operator)

Add a JOIN clause to this Impel.Criteria.

Currently only JOIN and LEFT JOIN are supported join opperators.

Parameters:
{String} left: The peer_column (table) that is the left side of the JOIN, e.g., "PlayerPeer::card_table_id"
{String} right: The peer_column (table) that is the right side of the JOIN, e.g., "CardTablePeer::id"
{String} operator Optional, Default: Impel.CritConstants.JOIN: The type of JOIN, e.g., Impel.CritConstants.LEFT_JOIN

<static> Impel.Criteria.addOr(peer_columnOrCrit, value, comparison)

Add a Impel.Criterion to this Impel.Criteria object. If this Impel.Criteria contains other Impel.Criterion the Impel.Criterion will be added with an 'OR' conjunction

Parameters:
{Impel.Criterion|String} peer_columnOrCrit
{String} value
{String} comparison Optional, Default: Impel.CritConstants.EQUAL

<static> Impel.Criteria.addSelectColumn(peer_column)

Add a column to the SELECT clause of the SQL statement that will be executed against the database.

The ImpelPeer.doSelect, etc., methods automatically add the necessary columns to the SELECT clause, so this method does not need to be called manually. If you do call it then only columns that have associated attributes in the ImpelClass object will be hydrated. To get at the column you will need to pass the Impel.Criteria to the ImpelPeer.executeSQL method then access the SQLResultSet that it passes off to your success callback.

var c = new Impel.Criteria();
    c.add("PlayerPeer::debt",50000,Impel.CritConstants.GREATER_EQUAL);
    c.addSelectColumn.("PlayerPeer::name");
    c.addSelectColumn.("PlayerPeer::address");
    PlayerPeer.executeSQL(c.getSelectSQL,c.getValues(),function(rs){
                        new Impel.ResultSet(rs).toArray().each(function(row){
                          notify.show("Lenny go collect from "+ row[0] +". He lives at "+ row[1]);
                        });
                      })

Parameters:
{String} peer_column: The Peer::column to add.

See:: Impel.Criteria#getSelectColumns

<static> Impel.Criteria.addTable(table)

Add a table to the list of tables that will be used in any SQL statement constructed from this Impel.Criteria. The ImpelPeer.doSelectOne, etc., methods automatically add the necessary tables, so this method really shouldn't be called outside of the ImpelPeer methods.

Parameters:
{String} table: The name of the table to add

<static> {String} Impel.Criteria.getDeleteSQL()

Retrieve a complete SQL DELETE statement constructed from this Impel.Criteria.

Returns:: {String} An SQL DELETE statement

See:: ImpelClass#remove

<static> {String} Impel.Criteria.getInsertSQL()

Retrieve a complete SQL Insert statement constructed from this Impel.Criteria.

The columns, values, and table names, will be automatically added to the statement before it is returned

  var c = new Impel.Criteria();
      c.add("PlayerPeer::name","Johnny Big");
      c.add("PlayerPeer::debt",0);
      c.add("PlayerPeer::card_table_id",7);

  PlayerPeer.executeSQL(c.getInsertSQL(),c.getValues(),$empty,
                        function(e){
                          notify.error("Failed to add Jonny to DB:",e);
                        });

Returns:: {String} An SQL INSERT statement

See:: ImpelClass#save

<static> {Object} Impel.Criteria.getLeftJoinClauses()

Retrieve an Object representing the LEFT JOIN clauses that have been added to this Impel.Criteria.

The left_joins DataStructure looks like this:
{ right_table_name : { 'ON' : " ON left_column = right_column", 'left' : left_table_name } }

We go through the each top level item of the Object; pull out the left table_table_name then look for any other entires that use it as their right_table_name. If we find any we add ourselves to the end of their ON clause and erase our entry. Then we go through the Object one more time constructing queries to look like left_table_name LEFT JOIN right_table_name ON left_colum = right_column LEFT JOIN another_right_table_name ON ..., left_table_name LEFT JOIN right_table_name ON left_colum = right_column.

The current implementation probably has a bug in that more than two nested LEFT JOINs using the same table won't come out correct. This will be fixed before we go to beta.

Returns:: {Object}

See:: Impel.Criteria#addJoin

<static> Impel.Criteria.getNewCriterion(peer_column, value, comparison)

Retrieve a new Impel.Criterion object that is not automatically added to this Impel.Criteria object. The returned Impel.Criterion can be used to chain other Impel.Criterions and create a more complex WHERE clause.

Parameters:
{String} peer_column: The peer and column that the reutrned Impel.Criterion should be associated with, e.g., "CardPeer::name"
{String} value: The value that the peer_column should be associated with, e.g., "Ace of Clubs"
{String} comparison: The relationship between the value and the peer_column, e.g., "Impel.CritConstants.EQUAL"

<static> {Array} Impel.Criteria.getSelectColumns()

Retrieve a list of columns that will be used to make up the SELECT

Returns:: {Array} The columns

See:: Impel.Criteria#addSelectColumn

<static> {String} Impel.Criteria.getSelectModifiers()

Retrieve any modifiers that have been added to the SELECT clause of the Impel.Criteria.

Returns:: {String} "DISTINCT" || '';

See:: Impel.Criteria#setDistinct

<static> {String} Impel.Criteria.getSelectSQL()

Retrieve a complete SQL SELECT statment constructed from this Impel.Criteria.

The select columns, table names, joins, and where clauses will be automatically added to the statement before it is returned

Returns:: {String} an SQL SELECT statement

See:: ImpelPeer#doSelect

<static> {String} Impel.Criteria.getTableNames()

Retrive a list of all the tables that will be used in any SQL statement constructed from this Impel.Criteria.

var c = new Impel.Criteria();
    c.add("PlayerPeer::name","Johnny Small");
    c.add("CardTablePeer::number",7);

var tables = c.getTableNames();

tables now equals "player,cardtable"

Returns:: {String} A list of the tables separated by commas

See:: Impel.Criteria#addTable

<static> {String} Impel.Criteria.getUpdateSQL(constrainCrit)

Retrieve a complet SQL Update statement constructed from this Impel.Criteria.

Parameters:
constrainCrit

Returns:: {String} An SQL UPDATE statement

See:: ImpelClass#save

<static> {Array} Impel.Criteria.getValues()

Retrieve all values that have been added to this Impel.Criteria in the order they were added.

The getInsertSQL, etc., methods construct the SQL statemetn with '?' in place of values. ImpelPeer.executeSQL expects this and so requires an array of variables as the second argument. It will then prepare the values before executing the full SQL statement.

Returns:: {Array} The values associated with this Impel.Criteria in the order they were added.

See:: ImpelPeer#executeSQL

<static> {String} Impel.Criteria.getWhereClause()

Retrieve only the WHERE clauses portion of an SQL statement constructed from this Impel.Criteria.

Returns:: {String} The WHERE clause for this Impel.Criteria.

See:: Impel.Criteria#getSelectSQL; Impel.Criteria#getUpdateSQL

<static> {boolean} Impel.Criteria.hasSelectColumns()

Does this Impel.Criteria contain any columns that will be used in the SELECT clause of an SQL statment?

Returns:: {boolean}

See:: Impel.Criteria#addSelectColumn; Impel.Criteria#getSelectColumns

<static> {Boolean} Impel.Criteria.leftJoinsHas(peer_column)

Does this Impel.Criteria contain a LEFT JOIN clause for the given peer_column.

Parameters:
peer_column

Returns:: {Boolean}

<static> Impel.Criteria.setDistinct()

Add the DISTINCT modifier to the SELECT clause of any SQL statement constructed from this Impel.Criteria.

<static> Impel.Criteria.setLimit(limit)

Set a limit on the number of results.

Parameters:
{Number} limit

Class Impel.Criteria

Impel takes the pain out of working with HTML5 asynchronous databases.

Latest News

What’s an ORM