DAOFactory:  Using the DAO Factory with CF Applications

by Oscar Arevalo
[email protected]
Last Update: March 12, 2008

About DAOFactory

DAOFactory is a set of components that provide a mechanism to interact with a persistent storage 
medium for ColdFusion applications via the use of different Data Access Objects (DAOs). Each 
DAO provides a common interface for the application to deal with frequently used backend data 
operations such as retrieving single and multiple records, and deleting, inserting and updating 
records.

Additionally, DAOFactory abstracts the specific details on how to interact with a particular storage 
medium,   opening   the   possibility   to   use   different   mechanisms   such   as   XML   files,   different 
database engines or even different database configurations.

Integrating DAOFactory into your Applications

DAOFactory is a package comprised of several components within a single directory. There is no 
requirement as for the placement or directory naming of the package.

The following sections describe the steps required for using the DAO Factory components in an 
application.

- Create DAOs
- Define DAO Factory configuration
- Using the factory

Creating DAOs

All applications that use DAOFactory need to define the individual DAOs that will be used. Each 
entity   on   the   domain   model   that   needs   to   be   persisted   needs   its   own   DAO.   The   naming 
convention is to use the entity name followed by “DAO”. For example, for an entity “Person”, the 
DAO will be named “personDAO.cfc”. 

All DAOs must extend the dao.cfc object provided in the DAOFactory package.

All   DAOs   should   be   placed   in   the   same   directory.   This   can   be   any   directory,   but   it   is 
 DAOFactory

recommended to create a directory that will be used only to place the DAO components.

As mentioned before, all DAOs must extend dao.cfc; however they are required to override the 
function   “initTableParams”.   This   function   is   used   to   programmatically   describe   the   particular 
entity. That is, it describes the field names, their data types, the name of the entity in the storage 
medium (i.e the table name), and the entity’s identity field.

See the following sample code of a dao named PersonDAO.cfc

<cfcomponent extends="DAOFactory.dao.DAO">
<cffunction name="initTableParams" access="package" returntype="void">
<cfset setTableName("users")>
<cfset setPrimaryKey("userID","cf_sql_varchar")>

<cfset addColumn("firstName", "cf_sql_varchar")>

<cfset addColumn("lastName", "cf_sql_varchar")>
<cfset addColumn("email", "cf_sql_varchar")>
</cffunction>
</cfcomponent>

The following table describes the methods used to describe the entity:

Method Description
setTableName Defines   the   name   of   the   entity   on   the   storage   medium.   For   example 
when storing the entity on the database, this would be the table name; or 
if using XML documents for storage, then this would be the file name of 
the XML document. Calling this method is required.

Arguments:
Name:   (string, required) The name to use.
setPrimaryKey Defines   the   field   that   is   the   identity   field   for   the   entity.   DAOFactory 
requires that all entities have a unique identity field. Calling this method 
is required.

Arguments:
Name:  (string, required) the name of the field
Type: (string, required) the datatype of the field using standard “cf_sql_*” 
naming convention. 
setLabelField Defines a field as being the “label” field for the entity. The use of this is 
completely   optional   and   is   only   used   when   calling   the   getByLabel() 
method on the DAO. This is only provided as a quick way of locating 
records for entities in which there is a field (other than the primary key) 
that can unique identify a record but in a human readable way (i.e. name, 
code, etc)

Arguments:

Page 2 of 6
 DAOFactory

Name:  (string, required) the name of the field
Type: (string, required) the datatype of the field using standard “cf_sql_*” 
naming convention.
addColumn Use this function multiple times to describe each field on the entity. It is 
not necessary to describe every single column or field of the entity, only 
those   that  will  be   used  or   affected  by  a   DAO  operation.   For   example 
columns like timestamps that will take values automatically assigned by 
the database, do not need to be defined.

NOTE: The primary key or identity field of the entity, does not need to be 
added using addColumn() since it is already declared by the use of the 
setPrimaryKey() method.

Arguments:
Name:  (string, required) the name of the field
Type: (string, required) the datatype of the field using standard “cf_sql_*” 
naming convention.

 
DAOFactory Configuration

DAOFactory   configuration   is   done   via   an   XML   document   that   is   read   by   the   DAOFactory.cfc 
component. This document indicates the type of mechanism that will be used to store the data 
(the dataProvider), the location of the application DAOs and any setting specific to the selected 
storage medium (paths, datasources, username, etc)

The following is a sample configuration file for the current example:

<?xml version="1.0" encoding="ISO-8859-1"?>

<config>
<!-- define data provider type -->
<dataProviderType>xml</dataProviderType>

<!-- this is the path to where the DAOs for the application are stored -->
<clientDAOPath>DAOFactory.db.</clientDAOPath>

<properties>
<!-- xml storage -->
<property name="dataRoot" value="/DAOFactory/data/" />
</properties>
</config>

Tag Name Parent Tag Description

<config> Document root
<dataProviderType> <config> Defines the type of data provider to use. To use a 
given   data   provider,   the   corresponding 
implementation tag must exist on the DAOFactory 

Page 3 of 6
 DAOFactory

package. The data provider determines which type 
of mechanism will be used to interact with the data: 
database, xml files, multiple databases, etc.
<clientDAOPath> <config> Path   to   the   directory   where   all   the   DAOs   for   the 
application are stored. The path must be expressed 
in dot notation and must end with a . (dot)
<properties> <config>
<property> <properties Use   one   or   more   property   tags   to   define   the 
> properties   specific   to   the   selected   data   provider. 
Use the attributes name and value to indicate the 
name of the property and the value that it takes.

DAOFactory includes three types of data providers: xml, db and fo (failover). However, new data 
provider classes can be created to support other types of storage mechanisms. The following 
table describes the properties for each type:

DataProviderType Implementation CFC Property  Description

xml xmlDataProvider dataRoot Relative path where to store the 
xml documents. Each entity has 
its own xml document.
db dbDataProvider dsn Datasource
dbType Type of database: mysql, oracle, 
mssql
username Username
password Password
fo foDataProvider dsn1 Datasource name
dsn2 Alternate datasource, this will be 
used  when   a   database   error  is 
detected   while   using   the   first 
dsn
username Username
password Password

Using the Factory

Once the DAOs and the configuration are done, the application can use the factory to produce 
instances of the DAO objects. As mentioned before, there is a DAO for each entity of interest in 
the application.

Before using the factory, this must be first initialized with the configuration xml. To initialize and 

Page 4 of 6
 DAOFactory

configure the factory just create an instance of the DAOFactory.cfc component and call its Init() 
method, passing as a parameter the relative path to the configuration document.

For example:

myDAOFactory = createObject(“component”, “dao.DAOFactory”).init (“/test/dao-config.xml”)

After  the   factory   is  created,  to   request   an  instance   of   a   particular  DAO,  just   call  the   method 
getDAO() on the factory. getDAO() takes a single parameter which is the entity name. The factory 
will append the word “DAO” to the entity name and will look for a cfc with that name inside the 
DAOs directory indicated in the config document.

personDAO = myDAOFactory.getDAO(“person”)

Now,   the   application   can   use   the   resulting   personDAO   object   to   interact   with   the   persistent 
storage of person data.

NOTE: Since the configuration will typically not change during the lifetime of the application, it is 
recommended to cache the factory instance on a persistent scope like the Application scope and 
just use one single instance to create the DAOs.

The following table describes the methods exposed by each DAO object:

Method Return Type Description

get Query Retrieves a single record identified by the primary key of the 
entity.

Arguments:
ID: the value of the primary key to search for. Required.
getAll Query Returns a query with all records on the table.

Arguments:
None.
getByLabel Query Retrieves a single record using the field defined as “label field” 
on the DAO setup.

Arguments:
Label: The value to look for. Required.
delete Void Deletes a single record identified by the given primary key.

Arguments:
ID: the value of the primary key to search for. Required.
save Any Performs either an insert or an update to the data store. If the 

Page 5 of 6
 DAOFactory

value passed on the parameter ID is 0, or if the a parameter 
named   “ID”   is   missing,   then   the   operation   is   considered   an 
Insert, otherwise it is considered an Update.

This method looks at all the arguments and uses the argument 
names and values as the data to insert. Only parameter names 
that   match   the   columns   described   in   the   initTableParams() 
method will be included in the Insert/Update.

Arguments.
ID:  the value  of the  primary  key. This  is only  required  when 
updating an existing record.
All other parameters are the data to be inserted.
search Query Performs an open search on the given entity data. This method 
will only search the current entity and will use any parameter 
name and value sent as the criteria for the search.

Arguments:
All arguments are used as the search criteria.

Page 6 of 6