Class ImpelClass

Any class of objects that is to be persisted via Impel must Extend the ImpelClass, contain a 'peer_class' attribute, and be within the scope of window.

Your classes can have any attributes or methods that you want, but only attributes that are defined in the column object of the associated peer class will be persisted. If you define a toString method the result of that method will be used when your object is used in String context.

Every instance of ImpelClass and it's inheritors must have an associated and instantiated ImpelPeer. The Peer object defines the attributes ImpelClass that will be persisted along with where in the database they will be saved.

Important Notes:

The ImpelPeer object must be declared after the ImpelClass class.
Unlike ImpelPeer, ImpelClass should not be directly instantiated. Instead you should create another class that extends ImpelClass
Define the member attributes of this class, that will be persisted, through an associated instance of ImpelPeer.
Member attributes defined via an ImpelPeer will automatically be accessible by get and set methods. If you want to override the getters and setters then define one ImpelClass along with an ImpelPeer then define another ImpelClass that extends the first. If you don't your customizations will be overwritten.
You must define the peer_class member manually.

Class Summary
Constructor Attributes	Constructor Name and Description
	ImpelClass(options, events) Any class of objects that is to be persisted via Impel must Extend the ImpelClass, contain a 'peer_class' attribute, and be within the scope of window.

Method Summary
Method Attributes	Method Name and Description
<static>	ImpelClass.dbug() Log the this objects attributes to the console.
<static>	ImpelClass.generateDocs() Generate a documentation page for this object detailing all of it's get and set methods, which are automatically generated by the peer.
<static>	ImpelClass.getDbug() Generate a string representing this object's attributes and their current values.
<static>	ImpelClass.getPeer() Retrieve the Peer object from memory.
<static>	ImpelClass.hydrate(attrs) Convert an array of columns:values retrieved from the database into attributes of this object.
<static>	ImpelClass.isModified() Has this object been modified since it was last retreived from the database
<static>	ImpelClass.isNew(boolean) Set this object to new or retireve its current state.
<static>	ImpelClass.remove(f_callback({String} error)) Remove this object from the database Tell the Peer that this object is being removed, so that it cannot be saved by another process, delete it and then mark it as deleted, so that it cannot be used.
<static>	ImpelClass.removed() Mark this object as having been deleted, so that it cannot be saved or updated.
<static>	ImpelClass.save(f_callback({String} error)) Persist this object in the database or update the appropriate database row to reflect changes in this object since it was last instantiated.
<static>	ImpelClass.saveMtoMObjsandLink(f_callback(string error), wasNew) Save any related many-to-many objects along with the link between this object and them.
<static>	ImpelClass.saveOneToManyObjs(f_callback(string error)) Save any objects that have a one-to-many relationship with this one.
<static>	ImpelClass.saveOnlyMe(f_callback(string error)) Save this object, but don't bother saving any related objects.
<static>	ImpelClass.setAttributes(attrs) Take a list of JSON objects and convert it into attributes for this object.
<static>	ImpelClass.setOptions(options) This is a vestigial method that should be removed as it exists verbatim in the parent class.
<static>	ImpelClass.updateIdFromRS(rs) After the base peer saves the object to the database it wil call this method on the saved object with an SQLResultSet, that should contain the id of the newly inserted row.

Class Detail

ImpelClass(options, events)

        var Card = new Class({
                             Extends       : ImpelClass,
                             peer_class    : "CardPeer",
                             toString      : function(){
                                               return this.getKanji();
                                             }
                   });

        var CardPeer = new ImpelPeer({
                             'columns'     :   { 
                                                 'id'          : 'card.id', 
                                                 'kanji'       : 'card.kanji', 
                                                 'hatsuon'     : 'card.hatsuon',
                                                 'meaning'     : 'card.meaning', 
                                                 'level'       : 'card.level', 
                                                 'created_at'  : 'card.created_at',
                                                 'updated_at'  : 'card.updated_at'
                                                },
                             'table'         : 'card',
                             'base_object'   : 'Card'
                      });

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

See:: ImpelPeer

Method Detail

<static> ImpelClass.dbug()

Log the this objects attributes to the console.

<static> {String} ImpelClass.generateDocs()

Generate a documentation page for this object detailing all of it's get and set methods, which are automatically generated by the peer. This method should only be called on a new object.

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

 /**
  * @param   {mixed} v The value to set the corresponding internal meaning attribute
  * @returns {undefined}
  */
  setMeaning : function (v) { 
                 this.attributes[attr] = v;
                 this.modified_columns.push(attr);
               }

 /**
  * Retrieve the corresponding internal level attribute
  * @returns {mixed} The corresponding internal attribute
  */
  getLevel : function () { 
                 return this.attributes[attr]; 
              }

 /**
  * Add an associated 1-m or m-m Stack object to object 
  * @returns {undefined} 
  */
  addStack : function (obj) {
                if(this.attributes[holder] == null)
                   this.attributes[holder] = [];
                if(this.attributes[holder][obj.getId()] == null)
                  this.attributes[holder].push(obj);
             }

 /**
  * Retrieve the associated 1-m or m-m Stack objects from this object's internal 
  * storage; Not the database.
  * @returns {Stack[]} An array of the associated objects 
  */
  getStacks : function () { 
                 return this.attributes[holder] 
               }

See:: ImpelPeer#generateDocs

<static> ImpelClass.getDbug()

Generate a string representing this object's attributes and their current values.

<static> ImpelClass.getPeer()

Retrieve the Peer object from memory.

<static> ImpelClass.hydrate(attrs)

Convert an array of columns:values retrieved from the database into attributes of this object.

When a SELECT statement is executed on two tables that contain a column with the same name the column name will be prepended with a the table name and a period, e.g., [table.]column. We need to strip off that table name specifier and use only the column name as an attribute. It is also possibe that the results of the query could include columns that are not a part of this class, so we check if the table matches our peer's table name before using the column.

Parameters:
{Object} attrs: - The column/value pairs retrieved from the database

<static> ImpelClass.isModified()

Has this object been modified since it was last retreived from the database

<static> ImpelClass.isNew(boolean)

Set this object to new or retireve its current state. If only javascript class methods could be made private ....

Parameters:
boolean: b - If b is defined and is a boolean this objects new status will be set to the value of b.

<static> ImpelClass.remove(f_callback({String} error))

Remove this object from the database

Tell the Peer that this object is being removed, so that it cannot be saved by another process, delete it and then mark it as deleted, so that it cannot be used. The object still exists in memory though ...

Parameters:
{function} s_callback({Object} Impel.ResultSet) Optional, Default: null: - The callback to use if the remove is succesful
{function} f_callback({String} error) Optional, Default: null: - The callback to use if the remove is not successful

<static> ImpelClass.removed()

Mark this object as having been deleted, so that it cannot be saved or updated. This, hopefully, eliminates at least one class of race condition.

<static> ImpelClass.save(f_callback({String} error))

Persist this object in the database or update the appropriate database row to reflect changes in this object since it was last instantiated.

If there are other objects associated with this one via 1-m and m-m relationships they will be automatically saved/updated if necessary.

If the object contains an updated_at or created_at member they will automatically be set to the appropriate time

Parameters:
{function} s_callback({Object} Impel.ResultSet) Optional, Default: null: - The callback to use if the save is succesful
{function} f_callback({String} error) Optional, Default: null: - The callback to use if the save is not successful

See:: ImpelClass#saveOnlyMe

<static> ImpelClass.saveMtoMObjsandLink(f_callback(string error), wasNew)

Save any related many-to-many objects along with the link between this object and them.

If this object was new then there is no possibility that the joining table has an entry for this object and it's related objects, so we must save the link. The related object may not have been previously saved though. If the related object is new then it won't have an id so we can't save the connecting object until after we've saved it.

If this object was not new then it is possible that a link already exists in the database between it and its related objects. We have to check for that link before creating new ones.

Parameters:
{function} s_callback(object Impel.ResultSet) Optional, Default: null: - The callback to use if the save is succesful
{function} f_callback(string error) Optional, Default: null: - The callback to use if the save is not successful
{boolean} wasNew: - Inidicates that this object was new before calling this method. If this parameter is not accurate then the database could become inconsistent

See:: ImpelClass#saveOneToManyObjs

<static> ImpelClass.saveOneToManyObjs(f_callback(string error))

Save any objects that have a one-to-many relationship with this one.

Use the Peer's list of one-to-many relationships to access this objects get method for one-to-many objects. Iterate over the list of objects and update any of them that don't have our id, i.e. aren't recorded as being related to this object.

Parameters:
{function} s_callback(object Impel.ResultSet) Optional, Default: null: - The callback to use if the save is succesful
{function} f_callback(string error) Optional, Default: null: - The callback to use if the save is not successful

See:: ImpelClass.saveMtoMObjsandLink

<static> ImpelClass.saveOnlyMe(f_callback(string error))

Save this object, but don't bother saving any related objects.

If the object is new use an INSERT statement, but if it is not use an UPDATE statement. Also don't bother with attributes that haven't been set.

If the object contains an updated_at or created_at member they will automatically be set to the appropriate time

Parameters:
{function} s_callback(object Impel.ResultSet) Optional, Default: null: - The callback to use if the save is succesful
{function} f_callback(string error) Optional, Default: null: - The callback to use if the save is not successful

See:: ImpelClass.save; Impel.Criteria#getInsertSQL; Impel.Criteria#getUpdateSQL

<static> ImpelClass.setAttributes(attrs)

Take a list of JSON objects and convert it into attributes for this object. The attributes will be accessible via camelCase named getters, e.g., updated_at is accessible via the getUpdatedAt method. This method should really only be called internally via the hydrate method.

Parameters:
{Object} attrs

<static> ImpelClass.setOptions(options)

This is a vestigial method that should be removed as it exists verbatim in the parent class.

Parameters:
{Object} options

<static> ImpelClass.updateIdFromRS(rs)

After the base peer saves the object to the database it wil call this method on the saved object with an SQLResultSet, that *should* contain the id of the newly inserted row.

We check for the id, update ourselves with it and take ourselves out of the saving state.

Parameters:
{SQLResultSet} rs: - The result set returned by the database query

See:: ImpelPeer#executeSQL; ImpelClass#saveOnlyMe

Class ImpelClass

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

What’s an ORM