Record

Moduleejs.db
Definition class Record
InheritanceRecord inherit Object
Specifiedejscript-1.1
StabilityEvolving.

Database record class.

A record instance corresponds to a row in the database. This class provides a low level Object Relational Mapping (ORM) between the database and Ejscript objects. This class provides methods to create, read, update and delete rows in the database. When read or initialized object properties are dynamically created in the Record instance for each column in the database table. Users should subclass the Record class for each database table to manage.


Properties

QualifiersPropertyTypeDescription
No properties defined

Record Methods

QualifiersMethod
static afterFilter(fn, options: Object = null): Void
 Run filters after saving data.
static beforeFilter(fn, options: Object = null): Void
 Run filters before saving data.
static belongsTo(owner, options: Object = null): Void
 Define a belonging reference to another model class.
error(field: String, msg: String): Void
 Set an error message.
static find(key: Object, options: Object = expression): Object
 Find a record.
static findAll(options: Object = expression): Array
 Find all the matching records.
static findOneWhere(where: String): Object
 Find the first record matching a condition.
static findWhere(where: String, count: Number = null): Array
 Find records matching a condition.
static getColumnNames(): Array
 Return the column names for the table.
static getColumnTitles(): Array
 Return the column names for the record.
static getColumnType(field: String): String
 Get the type of a column.
static getDb(): Database
 Get the database connection for this record class.
getErrors(): Array
 Get the errors for the record.
static getKeyName(): String
 Get the key name for this record.
static getNumRows(): Number
 Return the number of rows in the table.
static getTableName(): String
 Get the associated name for this record.
static hasAndBelongsToMany(model: Object, options: Object = expression): Void
 Define a containment relationship to another model class.
hasError(field: String = null): Boolean
 Check if the record has any errors.
static hasMany(model: Object, options: Object = expression): Void
 Define a containment relationship to another model class.
static hasOne(model: Object, options: Object = null): Void
 Define a containment relationship to another model class.
Record(fields: Object = null)
 Construct a new record instance.
static remove(keys: Array): Void
 Remove records from the database.
save(): Boolean
 Save the record to the database.
saveUpdate(fields: Object): Boolean
 Update a record based on the supplied fields and values.
static setDb(database: Database)
 Set the database connection for this record class.
static setKeyName(name: String): Void
 Set the key name for this record.
static setTableName(name: String): Void
 Set the associated table name for this record.
static sql(cmd: String, count: Number = null): Array
 Run an SQL statement and return selected records.
static trace(on: Boolean): Void
 Trace SQL statements.
validateRecord(): Boolean
 Validate a record.
static wrapFilter(fn, options: Object = null): Void
 Run filters before and after saving data.

Method Detail

static afterFilter(fn, options: Object = null): Void

Run filters after saving data.

Parameters
fn Function to run.
options: Object - reserved. [default: null]

static beforeFilter(fn, options: Object = null): Void

Run filters before saving data.

Parameters
fn Function to run.
options: Object - reserved. [default: null]

static belongsTo(owner, options: Object = null): Void

Define a belonging reference to another model class.

Description
When a model belongs to another, it has a foreign key reference to another class.
Parameters
owner Referenced model class that logically owns this model.
options: Object Optional options hash. [default: null]
Options
classNameName of the class.
foreignKeyKey name for the foreign key.
conditionsSQL conditions for the relationship to be satisfied.

error(field: String, msg: String): Void

Set an error message.

Description
This defines an error message for the given field in a record.
Parameters
field: String Name of the field to associate with the error message.
msg: String Error message.

static find(key: Object, options: Object = expression): Object

Find a record.

Description
Find and return a record identified by its primary key if supplied or by the specified options. If more than one record matches, return the first matching record.
Parameters
key: Object Key Optional key value. Set to null if selecting via the options.
options: Object Optional search option values. [default: expression]
Options
columnsList of columns to retrieve.
conditions{ field: value, ...} or [ "SQL condition", "id == 23", ...].
fromLow level from clause (not fully implemented).
keys[set of matching key values].
orderORDER BY clause.
groupGROUP BY clause.
include[Model, ...] Models to join in the query and create associations for. Always preloads.
joinsLow level join statement "LEFT JOIN vists on stockId = visits.id". Low level joins do not create association objects (or lazy loaders). The names of the joined columns are prefixed with the appropriate table name using camel case (tableColumn).
limitLIMIT count.
depthSpecify the depth for which to create associations for belongsTo, hasOne and hasMany relationships. Depth of 1 creates associations only in the immediate fields of the result. Depth == 2 creates in the next level and so on. Defaults to one.
offsetOFFSET count.
preload[Model1, ...] Preload "belongsTo" model associations rather than creating lazy loaders. This can reduce the number of database queries if iterating through associations.
readonly
lock
Returns
A model record or null if the record cannot be found.
Throws
IOError: on internal SQL errors

static findAll(options: Object = expression): Array

Find all the matching records.

Parameters
options: Object Optional set of options. See find for list of possible options. [default: expression]
Returns
An array of model records. The array may be empty if no matching records are found.
Throws
IOError: on internal SQL errors

static findOneWhere(where: String): Object

Find the first record matching a condition.

Description
Select a record using a given SQL where clause.
Parameters
where: String SQL WHERE clause to use when selecting rows.
Returns
A model record or null if the record cannot be found.
Throws
IOError: on internal SQL errors
Example
rec = findOneWhere("cost < 200")

static findWhere(where: String, count: Number = null): Array

Find records matching a condition.

Description
Select a set of records using a given SQL where clause.
Parameters
where: String SQL WHERE clause to use when selecting rows.
count: Number [default: null]
Returns
An array of objects. Each object represents a matching row with fields for each column.
Example
list = findWhere("cost < 200")

static getColumnNames(): Array

Return the column names for the table.

Returns
An array containing the names of the database columns. This corresponds to the set of properties that will be created when a row is read using $find.

static getColumnTitles(): Array

Return the column names for the record.

Returns
An array containing the Pascal case names of the database columns. The names have the first letter capitalized.

static getColumnType(field: String): String

Get the type of a column.

Parameters
field: String Name of the field to examine.
Returns
A string with the data type of the column.

static getDb(): Database

Get the database connection for this record class.

Returns
Database instance object created via new $Database.

getErrors(): Array

Get the errors for the record.

Returns
The error message collection for the record.

static getKeyName(): String

Get the key name for this record.


static getNumRows(): Number

Return the number of rows in the table.


static getTableName(): String

Get the associated name for this record.

Returns
The database table name backing this record class. Normally this is simply a plural class name.

static hasAndBelongsToMany(model: Object, options: Object = expression): Void

Define a containment relationship to another model class.

Description
When using "hasAndBelongsToMany" on another model, it means that other models have a foreign key reference to this class and this class can "contain" many instances of the other models.
Parameters
model: Object Model. (not implemented).
options: Object Object hash of options. [default: expression]
Options
foreignKeyKey name for the foreign key. (not implemented).
throughString Class name which mediates the many to many relationship. (not implemented).
joinTable.(not implemented).

hasError(field: String = null): Boolean

Check if the record has any errors.

Parameters
field: String [default: null]
Returns
True if the record has errors.

static hasMany(model: Object, options: Object = expression): Void

Define a containment relationship to another model class.

Description
When using "hasMany" on another model, it means that other model has a foreign key reference to this class and this class can "contain" many instances of the other.
Parameters
model: Object Model class that is contained by this class.
options: Object Call options. [default: expression]
Options
thingsModel object that is posessed by this. (not implemented).
throughString Class name which mediates the many to many relationship. (not implemented).
foreignKeyKey name for the foreign key. (not implemented).

static hasOne(model: Object, options: Object = null): Void

Define a containment relationship to another model class.

Description
When using "hasOne" on another model, it means that other model has a foreign key reference to this class and this class can "contain" only one instance of the other.
Parameters
model: Object Model class that is contained by this class.
options: Object [default: null]
Options
thingModel that is posessed by this. (not implemented).
foreignKeyKey name for the foreign key (not implemented).
asString (not implemented).

public Record(fields: Object = null)

Construct a new record instance.

Description
This is really a constructor function, because the Record class is implemented by user models, no constructor will be invoked when a new user model is instantiated. The record may be initialized by optionally supplying field data. However, the record will not be written to the database until save is called. To read data from the database into the record, use one of the find methods.
Parameters
fields: Object An optional object set of field names and values may be supplied to initialize the record. [default: null]

static remove(keys: Array): Void

Remove records from the database.

Parameters
keys: Array Set of keys identifying the records to remove.

save(): Boolean

Save the record to the database.

Returns
True if the record is validated and successfully written to the database.
Throws
IOError: Throws exception on sql errors

saveUpdate(fields: Object): Boolean

Update a record based on the supplied fields and values.

Parameters
fields: Object Hash of field/value pairs to use for the record update.
Returns
True if the database is successfully updated. Returns false if validation fails. In this case, the record is not saved.
Throws
IOError: on database SQL errors

static setDb(database: Database)

Set the database connection for this record class.

Parameters
database: Database Database instance object created via new Database.

static setKeyName(name: String): Void

Set the key name for this record.


static setTableName(name: String): Void

Set the associated table name for this record.

Parameters
name: String Name of the database table to backup the record class.

static sql(cmd: String, count: Number = null): Array

Run an SQL statement and return selected records.

Parameters
cmd: String SQL command to issue. Note: "SELECT" is automatically prepended and ";" is appended for you.
count: Number [default: null]
Returns
An array of objects. Each object represents a matching row with fields for each column.

static trace(on: Boolean): Void

Trace SQL statements.

Description
Control whether trace is enabled for the actual SQL statements issued against the database.
Parameters
on: Boolean If true, display each SQL statement to the log.

validateRecord(): Boolean

Validate a record.

Description
This call validates all the fields in a record.
Returns
True if the record has no errors.

static wrapFilter(fn, options: Object = null): Void

Run filters before and after saving data.

Parameters
fn Function to run.
options: Object - reserved. [default: null]