Record

Moduleejs.db
Namespace"ejs.db"
Definitiondynamic class Record
InheritanceRecord inherit Object

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
public static ErrorMessages  

Record Methods

QualifiersMethod
public static afterFilter(fn, options: Object): Void
public static beforeFilter(fn, options: Object): Void
public static belongsTo(owner, options: Object): Void
 Define a belonging reference to another model class.
public static get columnNames(): Array
 Return the column names for the table.
public static get columnTitles(): Array
 Return the column names for the record.
public constructor(fields: Object): Void
 Construct a new record instance.
public error(field: String, msg: String): Void
public static find(key: Object, options: Object): Object
 Find a record.
public static findAll(options: Object): Array
 Find all the matching records.
public static findOneWhere(where: String): Object
 Find the first record matching a condition.
public static findWhere(where: String, count: Number): Array
 Find records matching a condition.
public static getDb(): Database
 Get the database connection for this record class.
public getErrors(): Array
public getFieldType(field: String): String
public static getKeyName(): String
 Get the key name for this record.
public static getNumRows(): Number
 Return the number of rows in the table.
public static getTableName(): String
 Get the associated name for this record.
public static hasAndBelongsToMany(thing: Object, options: Object): Void
 Define a containment relationship to another model class.
public hasError(field: String): Boolean
public static hasMany(model: Object, options: Object): Void
 Define a containment relationship to another model class.
public static hasOne(model: Object, options: Object): Void
 Define a containment relationship to another model class.
Record()
public static remove(keys: Array): Void
 Remove records from the database.
public save(): Boolean
 Save the record to the database.
public saveUpdate(fields: Object): Boolean
 Update a record based on the supplied fields and values.
public static setDb(dbase: Database): Void
 Set the database connection for this record class.
public static setKeyName(value: String): Void
 Set the key name for this record.
public static setTableName(name: String): Void
 Set the associated table name for this record.
public static setup(database: Database): Void
 Initialize the model.
public static sql(cmd: String, count: Number): Array
 Run an SQL statement and return selected records.
public static trace(on: Boolean): Void
 Trace SQL statements.
public static validateFormat(fields: Object, options: Object)
public validateModel(): Boolean
public static validateNumber(fields: Object, options: Object)
public static validatePresence(fields: Object, options: Object)
public static validateUnique(fields: Object, options: Object)
public static wrapFilter(fn, options: Object): Void

Method Detail

static public afterFilter(fn, options: Object): Void

static public beforeFilter(fn, options: Object): Void

static public belongsTo(owner, options: Object): 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

Options

className:

foreignKey: Key — name for the foreign key

conditions: SQL — conditions for the relationship to be satisfied


static get public columnNames(): 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 get public columnTitles(): 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.

public constructor(fields: Object): Void

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 recrod.

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

static public find(key: Object, options: Object): 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

Options

columns: List — of columns to retrieve

conditions: { — field: value, ...} or [ "SQL condition", "id == 23", ...]

from: Low — level from clause (TODO not fully implemented)

keys: [set — of matching key values]

order: ORDER — BY clause

group: GROUP — BY clause

limit: LIMIT — count

offset: OFFSET — count

include: { — table1: { table2: { table3: {}}}}

joins: Low — level join statement "LEFT JOIN vists on stockId = visits.id"

joinBelongs: Automatically — join all belongsTo models. Defaults to true. FUTURE

readonly:

lock:

Returns
A model record or null if the record cannot be found.

Throws

IOError: on internal SQL errors


static public findAll(options: Object): Array

Find all the matching records.

Parameters
options: Object Optional set of options. See $find for list of possible options.
Returns
An array of model records. The array may be empty if no matching records are found.

Throws

IOError: on internal SQL errors


static public 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 public findWhere(where: String, count: Number): Array

Find records matching a condition.

Description
Select a set of records using a given SQL where clause.
Parameters
count: Number
Returns
An array of objects. Each object represents a matching row with fields for each column.
Example
list = findWhere("cost < 200")

static public getDb(): Database

Get the database connection for this record class.

Returns
Database instance object created via new $Database.

public getErrors(): Array

public getFieldType(field: String): String

static public getKeyName(): String

Get the key name for this record.


static public getNumRows(): Number

Return the number of rows in the table.


static public getTableName(): String

Get the associated name for this record.

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

static public hasAndBelongsToMany(thing: Object, options: Object): 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
options: Object

Options

thing: Model

foreignKey: Key — name for the foreign key

through: String — Class name which mediates the many to many relationship

joinTable:


public hasError(field: String): Boolean

static public hasMany(model: Object, options: Object): 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

Options

things: Model — object that is posessed by this.

through: String — Class name which mediates the many to many relationship

foreignKey: Key — name for the foreign key


static public hasOne(model: Object, options: Object): 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

Options

thing: Model — that is posessed by this.

foreignKey: Key — name for the foreign key

as: String


Record()

static public remove(keys: Array): Void

Remove records from the database.

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

public 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


public 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 record is successfully updated. Returns false if validation fails and the record is not saved.

Throws

IOError: on database SQL errors


static public setDb(dbase: Database): Void

Set the database connection for this record class.

Parameters

static public setKeyName(value: String): Void

Set the key name for this record.


static public 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 public setup(database: Database): Void

Initialize the model.

Parameters
database: Database Reference to the database object.

static public sql(cmd: String, count: Number): Array

Run an SQL statement and return selected records.

Parameters
count: Number
Returns
An array of objects. Each object represents a matching row with fields for each column.

static public 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

static public validateFormat(fields: Object, options: Object)

public validateModel(): Boolean

static public validateNumber(fields: Object, options: Object)

static public validatePresence(fields: Object, options: Object)

static public validateUnique(fields: Object, options: Object)

static public wrapFilter(fn, options: Object): Void