Class ImpelPeer

A utility class for managing interactions between objects and their associated records in the database.

Any class of objects that you want to persist in the database must have an associated ImpelPeer object.

An ImpelPeer object defines the names of the attributes for the ImpelClass object, its associated table and columns in the database. It must also define the name of the ImpelClass object.

Class Summary
Constructor Attributes	Constructor Name and Description
	ImpelPeer(options, events) A utility class for managing interactions between objects and their associated records in the database.

Method Summary
Method Attributes	Method Name and Description
<static>	ImpelPeer.addSelectColumns(crit) Add the select columns, that are necessary to hydrate the associated ImpelClass object from a database row, to a Impel.Criteria object
<static>	ImpelPeer.addTable(crit) Add the table, in which this ImpelClass's data is stored in the database, to a Impel.Criteria object
<static>	ImpelPeer.doSelect(criteria, callback(ImpelClass), con) Retrieve a set of rows from the database and attempt to hydrate instances of this ImpelPeer's associated ImpelClass with the results.
<static>	ImpelPeer.doSelectJoinAll(criteria, callback(object), con, except) Retrieve objets of the ImpelClass that are associated with this ImpelPeer, but also retieve all the other ImpelClass objects that are associated with each object for this ImpelPeer.
<static>	ImpelPeer.doSelectJoinAllExcept(criteria, callback(object), except, con) Retrieve objets of the ImpelClass that are associated with this ImpelPeer, but also retieve all the other ImpelClass objects that are associated with each object for this ImpelPeer.
<static>	ImpelPeer.doSelectOne(criteria, callback(object), con) Retrieve a sing row from the database and attempt to hydrate an instance of this ImpelPeer's associated ImpelClass with the result.
<static>	ImpelPeer.doSelectOneJoinAll(criteria, callback(object), con, except) Retrieve a single object from the database, but include all of its associated objects.
<static>	ImpelPeer.executeSQL(stmt, values, s_callback(SQLResultSet), f_callback(Error), obj, obj_method, con) Execute an arbitrary SQL statement against the database.
<static>	ImpelPeer.generateAttributes() Dynamically build the attributes of the ImpelClass object associated with this ImpelPeer object based on the columns that were specified when instantiating this object.
<static>	ImpelPeer.generateDocs() Generate a documentation page for this object detailing all of it's doSelectJoin* methods, which are automatically generated.
<static>	ImpelPeer.generateMethods() Dynamically build the set/get methods of the ImpelClass object associated with this ImpelPeer object based on the columns that were specified when instantiating this object.
<static>	ImpelPeer.getBaseObjName() Retrieve the name of the class associated with this peer object.
<static>	ImpelPeer.getColumns(columns) Retrieve an internal object that defines the names of the attributes and columns for this ImpelPeer's associated ImpelClass.
<static>	ImpelPeer.getSelectColumns() Retrieve a comma separated list of the columns that will be used to create an SQL SELECT statement for this ImpelPeer.
<static>	ImpelPeer.getTableName() Retrieve the name of the table that is associate with this ImpelPeer.
<static>	ImpelPeer.hasMany(peer_column) Define an one-to-many relationship between this ImpelPeer and another.
<static>	ImpelPeer.hasManyThrough(peer_column, through_peer_column, through_peer_column_relation) Define a many-to-many relationship between this ImpelPeer and another via a third ImpelPeer.
<static>	ImpelPeer.isDeleting(id) Determine if Impel is currently deleting an ImpelClass with a specific id.
<static>	ImpelPeer.retrieveByPkId(id, callback(object), con) Retrieve a single object from the database based on its primary key (id).
<static>	ImpelPeer.retrieveByPkIdJoinAll(id, callback(object), con, except) Retrieve a single object from the database based on its primary key (id), but also retrieve its associated objects.
<static>	ImpelPeer.setDeleted(id) Record that an ImpelClass object has been deleted.
<static>	ImpelPeer.setDeleting(id) Record that an ImpelClass object is being deleted.

Class Detail

ImpelPeer(options, events)

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

Method Detail

<static> {Impel.Criteria} ImpelPeer.addSelectColumns(crit)

Add the select columns, that are necessary to hydrate the associated ImpelClass object from a database row, to a Impel.Criteria object

Parameters:
{Impel.Criteria} crit Optional: - The Impel.Criteria object that will be used to retrieve rows from the database

Returns:: {Impel.Criteria} If a Impel.Criteria object is not passed in one will be created and returned. If a Impel.Criteria object is passed in that it will be modified and returned, but because JavaScript passes object by reference you do not need to assign the return back to your Impel.Criteria object.

See:: Impel.Criteria#addSelectColumn

<static> {Impel.Criteria} ImpelPeer.addTable(crit)

Add the table, in which this ImpelClass's data is stored in the database, to a Impel.Criteria object

Parameters:
{Impel.Criteria} crit: - The Impel.Criteria object that will be used to retrieve rows from the database

Returns:: {Impel.Criteria} If a Impel.Criteria object is not passed in one will be created and returned. If a Impel.Criteria object is passed in that it will be modified and returned, but because JavaScript passes object by reference you do not need to assign the return back to your Impel.Criteria object.

See:: Impel.Criteria#addTable; ImpelPeer#getTableName

<static> {undefined} ImpelPeer.doSelect(criteria, callback(ImpelClass), con)

Retrieve a set of rows from the database and attempt to hydrate instances of this ImpelPeer's associated ImpelClass with the results. It is important to realize that doSelect and doSelectOne will only retrieve objects that are an instance of this ImpelPeer's ImpelClass. One-to-many and many-to-many relationships will not be maintaned. Use doSelectJoinAll or a similar function if this ImpelClass's objects are actually made up of multiple other ImpelClasses.

Parameters:
{Impel.Criteria} criteria: - The criteria used to limit the results retrieved. The appropriate table and columns will be added to the Impel.Criteria object automatically, so you only need to specify the pieces of the WHERE clause. It can also be an empty criteria, so doSelect(new Impel.Criteria(), ...) is fine if you want to retireve all of the associated objects from the database.
{function} callback(ImpelClass): - The function to call when the query completes.
{connection} con Optional: - The database connection to use. Impel.db will be used if it is undefined.

Returns:: {undefined} To access the ImpelClass objects that are retreived, pass in a callback function

See:: ImpelPeer#doSelectOne; ImpelPeer#doSelectJoinAll

<static> {undefined} ImpelPeer.doSelectJoinAll(criteria, callback(object), con, except)

Retrieve objets of the ImpelClass that are associated with this ImpelPeer, but also retieve all the other ImpelClass objects that are associated with each object for this ImpelPeer.

var c = new Impel.Criteria();
 c.add("CardPeer::id",119);
CardPeer.doSelectJoinAllExcept(c,function(cards){ ... }, null, ['CardScore','Stack']);

Parameters:
{Impel.Criteria} criteria: - The criteria used to limit the results retrieved. The appropriate table and columns will be added to the Impel.Criteria object automatically, so you only need to specify the pieces of the WHERE clause. It can also be an empty criteria, so doSelect(new Impel.Criteria(), ...) is fine if you want to retireve all of the associated objects from the database.
{function} callback(object): - The function to call when the query completes.
{connection} con Optional: - The database connection to use. Impel.db will be used if it is undefined.
{Array} except: - Do not JOIN with the peers in this array

Returns:: {undefined} To access the ImpelClass objects that are retreived, pass in a callback function.

<static> {undefined} ImpelPeer.doSelectJoinAllExcept(criteria, callback(object), except, con)

Retrieve objets of the ImpelClass that are associated with this ImpelPeer, but also retieve all the other ImpelClass objects that are associated with each object for this ImpelPeer.

var c = new Impel.Criteria();
 c.add("CardPeer::id",119);
CardPeer.doSelectJoinAllExcept(c,function(cards){ ... }, ['CardScore','Stack']);

Parameters:
{Impel.Criteria} criteria: - The criteria used to limit the results retrieved. The appropriate table and columns will be added to the Impel.Criteria object automatically, so you only need to specify the pieces of the WHERE clause. It can also be an empty criteria, so doSelect(new Impel.Criteria(), ...) is fine if you want to retireve all of the associated objects from the database.
{function} callback(object): - The function to call when the query completes.
{Array} except: - Do not JOIN with the peers in this array
{connection} con Optional: - The database connection to use. Impel.db will be used if it is undefined.

Returns:: {undefined} To access the ImpelClass objects that are retreived, pass in a callback function.

<static> {undefined} ImpelPeer.doSelectOne(criteria, callback(object), con)

Retrieve a sing row from the database and attempt to hydrate an instance of this ImpelPeer's associated ImpelClass with the result. It is important to realize that doSelect and doSelectOne will only retrieve objects that are an instance of this ImpelPeer's ImpelClass. One-to-many and many-to-many relationships will not be maintaned. Use doSelectJoinAll or a similar function if this ImpelClass's objects are actually made up of multiple other ImpelClasses.

Parameters:
{Impel.Criteria} criteria: - The criteria used to limit the results retrieved. The appropriate table and columns will be added to the Impel.Criteria object automatically, so you only need to specify the pieces of the WHERE clause. It can also be an empty criteria, so doSelect(new Impel.Criteria(), ...) is fine if you want to retireve all of the associated objects from the database.
{function} callback(object): - The function to call when the query completes.
{connection} con Optional: - The database connection to use. Impel.db will be used if it is undefined.

Returns:: {undefined} To access the ImpelClass objects that are retreived, pass in a callback function

See:: ImpelPeer#doSelect; ImpelPeer#doSelectJoinAll

<static> {undefined} ImpelPeer.doSelectOneJoinAll(criteria, callback(object), con, except)

Retrieve a single object from the database, but include all of its associated objects.

Important Note This method can be incredibly memory intensive if you have a lot of rows in the database. Make sure to pass in a good Impel.Criteria

Parameters:
{Impel.Criteria} criteria: - The criteria used to limit the results retrieved. The appropriate table and columns will be added to the Impel.Criteria object automatically, so you only need to specify the pieces of the WHERE clause. It can also be an empty criteria, so doSelect(new Impel.Criteria(), ...) is fine if you want to retireve all of the associated objects from the database.
{function} callback(object): - The function to call when the query completes.
{connection} con Optional: - The database connection to use. Impel.db will be used if it is undefined.
{Array} except: - Do not JOIN with the peers in this array

Returns:: {undefined} To access the ImpelClass object that is retreived, pass in a callback function.

See:: ImpelPeer#retrieveByPkIdJoinAll

<static> {undefined} ImpelPeer.executeSQL(stmt, values, s_callback(SQLResultSet), f_callback(Error), obj, obj_method, con)

Execute an arbitrary SQL statement against the database. If the query is succesfull call a particular method of a particular object. Also call specified success and failure callbacks as necessary.

Parameters:

{String} stmt

The SQL statement to execute

{Array} values Optional

A set of values to to insert into the SQL statement after properly perparing them

{function} s_callback(SQLResultSet) Optional

The function to call if the transaction succeeds

{function} f_callback(Error) Optional

The function to call if the transaction fails

{Object} obj

The object that is being affected by this transaction

{method} obj_method

The method in the object to call after the transaction succeeds

{database} con Optional

The database to execute against. If null then Impel.db is used

On success s_callback will be called with an SQLResultSet as an arument. An SQLResultSet contains:

int insertId: -1 if not insert was performed
int rowsAffected: 0 if no rows were updated or inserted
SQLResultSetRowList rows: the rows that were returned
- int length
- function item(index): retrieve the row at a given relative index

Returns:: {undefined} To access the data retrieved pass in a callback function, or an Object and a method to call.

<static> {undefined} ImpelPeer.generateAttributes()

Dynamically build the attributes of the ImpelClass object associated with this ImpelPeer object based on the columns that were specified when instantiating this object. It may at some point be worth while to write this into a code generator, so that it only needs to be called during development. Of course that would increase the size of the code delivered to the user, so it is a network bandwidth v.s. CPU utilization issue.

Important Notes:

The ImpelClass must be defined within the scope of window
This method should not be called directly because the constructor will call it. If you add columns to the peer after instantiation THEN call this method manually.

Returns:: {undefined} The ImpelClass class definition that is associated with this ImpelPeer instnace will be modified to include new attributes

<static> {String} ImpelPeer.generateDocs()

Generate a documentation page for this object detailing all of it's doSelectJoin* methods, which are automatically generated.

Important Note: The documentation does include the method definitons, but they cannot be copied verbatim into your code and substituted for the actual automatically generated methods.

Returns:

{String} A jsdoc-toolkit formatted string of declarations

/**
 * Retrieve objects from the database including their associated Compound m-m 
 * objects using CardCompound as an intermediary. 
 * @param   {Impel.Criteria} criteria The Impel.Criteria object to use to construct and limit 
 *                              the query. 
 * @param   {function} callback(Objects[]) The function to pass the results to 
 * @param   {Database} [con] The database connection to use.
 * @returns {undefined} The callback function will be used to pass the results back
 */
doSelectJoinCompoundThroughCardCompound : function (criteria, callback, con) {
    var c = this.addTable(this.addSelectColumns( criteria));
        c = peer_column.peer.addTable(peer_column.peer.addSelectColumns(c));
        c = through_peer_column.peer.addTable(c);
        c.addJoin(this.options.base_object+"Peer::id", through_peer_column.peer_name + "::" + through_peer_column.column, Impel.CritConstants.LEFT_JOIN);
        c.addJoin(peer_column.peer_name + "::" + peer_column.column, through_peer_column_relation.peer_name + "::" + through_peer_column_relation.column);

    this.executeSQL(c.getSelectSQL(),c.getValues(),
          function(rs){
            var objs   = $H({});
            new Impel.ResultSet(rs).toArray().each(function(row){
                var obj     = new window[this.options.base_object]();
                var robj    = new window[peer_column.peer.options.base_object]();
                    obj.hydrate(row);

                var id      = obj.getId();
                    objs.include(id,obj);
                    obj         = null;
                    obj         = objs.get(id);

                robj.hydrate(row);
                obj[adder](robj);
             },this);
           callback(objs);
        }.bind(this),
        function(e){ 
           throw("Query failed: "+e); 
        }
    );
}

See:: ImpelClass#generateDocs

<static> {undefined} ImpelPeer.generateMethods()

Dynamically build the set/get methods of the ImpelClass object associated with this ImpelPeer object based on the columns that were specified when instantiating this object. It may at some point be worth while to write this into a code generator, so that it only needs to be called during development. Of course that would increase the size of the code delivered to the user, so it is a network bandwidth v.s. CPU utilization issue.

Important Notes:

The ImpelClass must be defined within the scope of window
This method should not be called directly because the constructor will call it. If you add columns to the peer after instantiation THEN call this method manually.

Returns:: {undefined} The ImpelClass class definition that is associated with this ImpelPeer instance will be modified to include new methods

See:: ImpelClass#generateDocs

<static> {String} ImpelPeer.getBaseObjName()

Retrieve the name of the class associated with this peer object.

Returns:: {String} The name of the class associated with this peer object, e.g., CardPeer.getBaseObjName() will return "Card"

<static> {Object} ImpelPeer.getColumns(columns)

Retrieve an internal object that defines the names of the attributes and columns for this ImpelPeer's associated ImpelClass.

Parameters:
columns

Returns:

{Object} An object representing the attributes and columns for this ImpelPeer

{
  'id'          : 'player.id', 
  'name'        : 'player.name', 
  'created_at'  : 'player.created_at',
  'updated_at'  : 'player.updated_at'
}

<static> {String} ImpelPeer.getSelectColumns()

Retrieve a comma separated list of the columns that will be used to create an SQL SELECT statement for this ImpelPeer.

Important Note: The columns will be specified using AS clauses because the HTML 5, or SQLite, RDBMS impelementation will overwrite columns with the same name from separate tables.

Returns:: {String}

<static> {String} ImpelPeer.getTableName()

Retrieve the name of the table that is associate with this ImpelPeer.

Returns:: {String}

<static> {undefined} ImpelPeer.hasMany(peer_column)

Define an one-to-many relationship between this ImpelPeer and another.

This ImpelPeer will be modified to include methods to select its associated ImpelClass objects from the database along with the the related ImpelClass specified by the peer_column argument. This ImpelPeer's associated ImpelClass will also be modified to include methods for holding the related objects.

Any calls to save an ImpelClass that uses this ImpelPeer will also save any of the related objects that it has a one-to-many relationship with

Parameters:
{String} peer_column: The Peer::column that relates the two ImpelPeers.

Returns:

{undefined} This ImpelPeer will be modified to include new methods as will the prototype for the associated ImpelClass

Example

  CardTablePeer.hasMany("PlayerPeer::card_table_id");

This ImpelPeer (CardTablePeer) now includes the following method

  CardTablePeer.doSelectJoinPlayer(criteria,s_callback,con);

The related ImpelClass (CardTable) now includes the following methods

  CardTable.addPlayer(player);
  CardTable.getPlayers();

See:: ImpelClass#generateDocs

<static> {undefined} ImpelPeer.hasManyThrough(peer_column, through_peer_column, through_peer_column_relation)

Define a many-to-many relationship between this ImpelPeer and another via a third ImpelPeer.

Any calls to save an ImpelClass that uses this ImpelPeer will also save any of the related objects that it has a many-to-many relationship with. The save call will also keep the association up to date via the third ImpelPeer

Parameters:
{String} peer_column: The Peer::column that this ImpelPeer has a many-to-many relationship with.
{String} through_peer_column: The Peer::column that associates this Peer with the third Peer
{String} through_peer_column_relation: The peer::column that associates the related Peer with the third Peer

Returns:

{undefined} This ImpelPeer will be modified to include new methods as will the prototype for the associated ImpelClass

Example

  CardPeer.hasManyThrough("StackPeer::id", "CardStackPeer::card_id", "CardStackPeer::stack_id");

The ImpelPeer (CardPeer) now includes the following method

  CardPeer.doSelectJoinStackThroughCardStack(criteria,s_callback,con);

The related ImpelClass (CardTable) now includes the following methods

  Card.addStack(stack);
  Card.getStacks();

The Card.doSelectJoinAll method will take the many-to-many relationship between CardPeer and StackPeer into account; as will the Card.save() method.

Currently, you must manually specify both sides of the many-to-many relationship, so in our example we need to call StackPeer.hasManyThrough as well.

  StackPeer.hasManyThrough("CardPeer::id", "CardStackPeer::stack_id", "CardStackPeer::card_id");

The ImpelPeer (StackPeer) now includes the following method

  StackPeer.doSelectJoinStackThroughCardStack(criteria,s_callback,con);

The related ImpelClass (Stack) now includes the following methods

  Stack.addCard(card);
  Stack.getCards();

See:: ImpelClass#generateDocs

<static> ImpelPeer.isDeleting(id)

Determine if Impel is currently deleting an ImpelClass with a specific id.

This method is used by Impel to prevent certain race-conditions. It can be used externally, but there should be no need.

Parameters:
{Number} id: The id of the ImpelClass object to check.

<static> {undefined} ImpelPeer.retrieveByPkId(id, callback(object), con)

Retrieve a single object from the database based on its primary key (id).

Parameters:
{Number} id: - The value of the id for the object that you want to retrieve
{function} callback(object): - The function to call when the query completes.
{connection} con Optional: - The database connection to use. Impel.db will be used if it is undefined.

Returns:: {undefined} To access the ImpelClass object that is retreived, pass in a callback function.

See:: ImpelPeer#doSelectOne

<static> {undefined} ImpelPeer.retrieveByPkIdJoinAll(id, callback(object), con, except)

Retrieve a single object from the database based on its primary key (id), but also retrieve its associated objects.

Parameters:
{Number} id: - The value of the id for the object that you want to retrieve
{function} callback(object): - The function to call when the query completes.
{connection} con Optional: - The database connection to use. Impel.db will be used if it is undefined.
{Array} except: - Do not JOIN with the peers in this array

Returns:: {undefined} To access the ImpelClass object that is retreived, pass in a callback function.

See:: ImpelPeer#doSelectOneJoinAll

<static> ImpelPeer.setDeleted(id)

Record that an ImpelClass object has been deleted.

This method is used by Impel to prevent certain race-conditions. It can be used externally, but there should be no need.

Parameters:
{Number} id: The id of the ImpelClass object

<static> ImpelPeer.setDeleting(id)

Record that an ImpelClass object is being deleted.

This method is used by Impel to prevent certain race-conditions. It can be used externally, but there should be no need.

Parameters:
{Number} id: The id of the ImpelClass object

Class ImpelPeer

Example

This ImpelPeer (CardTablePeer) now includes the following method

The related ImpelClass (CardTable) now includes the following methods

Example

The ImpelPeer (CardPeer) now includes the following method

The related ImpelClass (CardTable) now includes the following methods

The ImpelPeer (StackPeer) now includes the following method

The related ImpelClass (Stack) now includes the following methods

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

Latest News

What’s an ORM