Usage

• Initiating the objectBreeze controller
• Create an object
• Interacting with the object
• Object Composition
• Using the Data Access Object
• Gateway
• Query Object
• Collections
• Collection specific functions

Initiating the objectBreeze controller:

The objectBreezeController is initialized as in the example below. In this instance, it is set into the APPLICATION scope. If you are using a framework, you could set this into your framework event. The possible values for database type are MSSQL, Oracle, MySQL and PostgreSQL.

Example:
<cfset APPLICATION.ob = createObject("component", "objectBreeze.assets.cfc.controller.objectBreeze").init("database_type", "datasource_name") />

All examples below assume you have set objectBreeze into some local scope. If you are using it from the application scope, simply add the line:
<cfset VARIABLES.objectBreeze = APPLICATION.objectBreeze />

Create an object:

objectBreeze.objectCreate(”tableName”)

objectCreate() will return an empty object that contains all the properties of the database table. Remember, objectBreeze requires that the table contain a primary key.

Example:
<cfset myTable = objectBreeze.objectCreate("myTable") />

Interacting with the object:

The object returned contains one property getter, one property setter method, and a getter and setter for the object’s primary key (id) value. These four methods will encapsulate the object and allow you to interact with the object.

object.getProperty(”propertyName”)

getProperty() returns the value of the specified property (column) within the object.

Example:
<cfset myValue = myTable.getProperty("FName") />
object.setProperty(”propertyName”, value)

setProperty() sets a new value into the specified property (column) within the object.

Example:
<cfset myValue = myTable.setProperty("FName", "Nic") />
objectName.getID()

getID() returns the value of the primary key property (column) in the object.

Example:
<cfset myID = myTable.getID() />
objectName.setID(”New_PK_Value”)

setID() sets the value of the primary key property (column) in the object.

Example:
<cfset myTable.setID(createUUID()) />

Object Composition:

objectBreeze allows you to compound objects, whether it be a compounded object or collection. You will still use the existing objectRead() and objectCommit() methods for compounded objects (you will learn about these methods in the DAO section below)

objectName.containsOne(”compounded_table_name”)

containsOne() creates an object within the existing object.

Example:
<cfset myTable.containsOne("myOtherTable") />
objectName.containsMany(”compounded_table_name”)

containsMany() creates a collection within the existing object.

Example:
<cfset myTable.containsMany("myCollection") />

Using the Data Access Object:

An object would be useless without a DAO to interact with the database using CRUD methods (CRUD = create, read, update, delete). The MasterObject contains four methods which allow you to interact with the database for an object.

object.read(”priKeyValue”)

read() loads the supplied object with a record from the database matching a primary key value. If the object contains other objects or collections, they will be read in at this time as well using the parent object’s primary key.

Example:
<cfset myTable = objectBreeze.objectCreate("myTable") />
<cfset myTable.read(1) />
object.readByProperty()

readByProperty() loads the supplied object with a record from the database matching any property values specified in the object. If the object contains other objects or collections, they will be read in at this time as well using the parent object’s primary key.

Note: readByProperty() can be used in conjunction with the queryObject. Once I have loaded my initial object from the queryObject, I can specify composition and call readByProperty() to load the entire matching composition.

Example:
<cfset objQuery = objectBreeze.list("MyTable") />
<cfset myTable = objQuery.getNext() />
<cfset myTable.containsMany("OtherTable") />
<cfset myTable.readByProperty() />
object.commit()

commit() will either insert or update the object in the database depending on whether or not the primary key value already exists in the database. If you are using an identity field, do not supply a value for the id. The object will be returned containing the new ID returned from the insert (see Developer Notes for more information for each database). If the table does not use an identity field, supply the value and it will be created with that value (such as a UUID). If the object contains other objects or collections (composition), these objects will be written to the database as well.

Example:
<cfset myTable.commit() />
object.delete()

delete() removes an object from the database by the primary key value defined in the object. This is a hard delete.

Example:
<cfset myTable.delete() />

Gateway:

objectBreeze allows you to query your datasource via a gateway. All gateway methods return a queryObject (see queryObject documentation below for usage).

objectBreeze.list(table_name, order_by_list)

list() returns all records in the table as a queryObject. You may send an optional order by statement, which is a list of properties to order by (ASC/DESC permitted).

objectBreeze.getByProperty(table_name, property_name, property_value, order_by_list (optional))

getByProperty() allows you to specify a single property to query by and returns a query object.

objectBreeze.getByWhere(table_name, SQL_where_clause, order_by_list (optional))

getByWhere() allows you to send a where statement to the query. This statement should not contain ‘WHERE’. You may also specify a list to order by.

queryObject:

objectBreeze returns a query object from any gateway method. The queryObject allow you to interact with the query, and easily turn records into objects.

queryObject.getQuery()

getQuery() returns the query as type query.

queryObject.getRecordCount()

getRecordCount() returns the number of records in the query object.

queryObject.hasPrevious()

hasPrevious() returns boolean result as to whether or not there is a previous record in the query.

queryObject.hasNext()

hasNext() returns boolean result as to whether or not there is a next record in the query.

queryObject.getPrevious()

getPrevious() returns the previous record in the query as an object.

queryObject.getNext()

getNext() returns the previous record in the query as an object.

Collections:

objectBreeze also creates collections of objects from your database. Since you may be creating your own data Gateways, objectBreeze also provides a way to load collections using a query returned from your Gateway. Below I have listed the primary collection functions.

objectBreeze.collectionCreate()

collectionCreate() creates a new collection of objects (array of structs)

Example:
<cfset myCollection = objectBreeze.collectionCreate() />
collection.collectionCommit()

collectionCommit() commits the entire collection of objects to the database using insert and update as needed depending on the record itself.

Example:
<cfset myCollection.collectionCommit() />
collection.collectionFillByQuery(”table_name”, query, “dbtype”, “dsn”)

collectionFillByQuery() allows you to pass a query from the table handled by a collection. This allows you to create a gateway for your object, and easily populate the object.

Example:
<cfset myCollection.collectionFillByQuery("myTable", myQuery, "MSSQL", "myDSN") />

Collection Specific Functions:

The methods below allow you to interact with the collection once it is created. These methods were adapted from code developed by Phill Nacelli.

collection.add(object) - adds an object to the collection

collection.getAt(position) - gets the object in the specified numeric position

collection.existsAt(position) - returns a Boolean value letting you know if an object exists in the specified position

collection.count() - returns a numeric value of the maximum position in the collection

collection.removeAt(position) - removes the object in the specified position, returns a Boolean value if an object was removed or not

collection.clearCollection() - clears the entire collection, but does not delete the collection

collection.getByID(primary_key_value) - returns an object from the collection that matches the primary key specified

collection.getByProperty(”property_name”, property_value) - returns an object from the collection that matches the value specified in the property specified

Developer Notes

The object created using objectBreeze contains several other methods that objectBreeze uses, but the average user does not necessarily need access to. Some may be useful for certain projects, such as object.getPropertyNames(), or hasOne() and hasMany() for composition. Dump the object for additional help, or feel free to contact me.

Auto ID datatypes per database are as follows:

• MSSQL - Identity
• MySQL - int(4) auto inc
• Oracle - Any sequence (user defined or system defined)
• PostgreSQL - serial