My Abstract Persistence Layer: Take 1

So in my last post I was able to get some pretty awesome feedback on some questions I had. I am not going to go over everything about the post so please check it out first and read through the comments. In the end I wanted to find out how I could abstract commons functionality of the persistence layer in my application. What I am starting with here is by no means the *right* answer or my final, just my first stab.

I am going to use the cfbookclub datasource that ships with ColdFusion 9 so you can follow along at home. First we need to setup our application. This is my basic directory structure for the application and below is my Application component.


component { // application settings this.name = "bookclub-orm"; this.applicationtimeout = createTimeSpan(0,2,0,0); this.sessionmanagement = true; this.sessiontimeout = createTimeSpan(0,1,0,0); // orm settings this.ormenabled = "true"; this.datasource = "cfbookclub"; this.ormsettings = { logSQL=true }; public boolean function onApplicationStart(){ application.Author = new model.dao.AuthorDAO(); application.Book = new model.dao.BookDAO(); return true; } public boolean function onRequestStart(String targetPage){ //url.reload = true; if(structKeyExists(url,"reload")){ onApplicationStart(); ormReload(); } return true; } }

Nothing special going on so far. I want to keep this example simple so I will not be using any frameworks. You will notice that in my application start method I am creating 2 static objects, we will get to that in a minute. First we need to setup our entities and for this example we will only be using the Author and book objects. In the domain folder I am going to create an author and book cfc's. Each of these components should look pretty familiar. We do define a relationship between the two as well. In a more complex example down the road we will get into the use of an abstract domain but for now we will keep it simple. component entityname="Author" persistent="true" table="AUTHORS" { property name="authorid" column="authorid" type="numeric" ormtype="int" fieldtype="id" ; property name="firstname" column="firstname" type="string" ormtype="string" ; property name="lastname" column="lastname" type="string" ormtype="string" ; property name="bio" column="bio" type="string" ormtype="clob" ; property name="isspotlight" column="isspotlight" type="string" ormtype="string" ; property name="books" fieldtype="one-to-many" cfc="Book" fkcolumn="authorid"; } component persistent="true" entityname="Book" table="BOOKS" { property name="bookid" ormtype="int" fieldtype="id"; property name="title" ormtype="string"; property name="bookdescription" ormtype="clob"; property name="bookimage" ormtype="string"; property name="thumbnailimage" ormtype="string"; property name="isspotlight" ormtype="string"; property name="genre" ormtype="string"; // many books to one author property name="author" fieldtype="many-to-one" cfc="Author" fkcolumn="authorid"; }

Now we have our entities ready to get we can get started on our persistence layer. In the dao folder I am going to create an AbstractDAO component. To keep it simple we are going to start out by defining only a few methods.

• New - I will create a new instance of the domain object.
• Load - I will load an existing object from a database based on the primary key.
• List - I will give you back a query of all the rows for this domain object.
• FindBy - I am a dynamic finder that allows you to find exact matches dynamically (findByFirstAndLast("Dan","Vega"))
• Save
• Delete

First we will setup the base of the component. Now I want this component to always be extended, never instantiated. To make sure of this we can throw an error if it this ever happens. /** * @displayname Abstract Service * @hint I provide common persistence functionality */ component { public void function init(){ throw(type="AbstractDAO",message="AbstractDAO is meant to be extended not instantiated"); } } Next we will create the new method. With this comes our first problem. Notice how I had to hard code the entity that we are working with. If we truly want to make this universal that this is not going to work. /** * @displayname Abstract Service * @hint I provide common persistence functionality */ component { public void function init(){ throw(type="AbstractDAO",message="AbstractDAO is meant to be extended not instantiated"); } /** * @hint I will return a new instance of the entity we are working with */ public any function new(){ return entityNew("Author"); } }

After a couple different attempts and some suggestions from others I finally came up with the following. First we are going to create our Author DAO component that extends the abstract dao object. /** * @displayname Author DAO * @accessors true */ component extends="AbstractDAO" { public AuthorDAO function init(){ return this; } } Next we are going to add a little helper method for getting the entity name. We will use this method for almost every method in our abstract dao. This method is a pretty great way of figuring out what entity we are working with. You can either add a entity attribute to the component and it will read that or you can follow a naming convention. In our case we are working with the Author entity so i named it AuthorDAO. private string function getEntity(){ var meta = getMetadata(this); var entity = ""; if(structKeyExists(meta,"entity")){ // get the meta data for the entity name entity = meta.entity; } else { // read the service name and extract the first part as the entity name if(structKeyExists(meta,"fullname")){ var service = listLast(meta.fullname,"."); entity = replaceNoCase(service,"dao",""); } } return entity; } Now with my get entity in place our method becomes much more dynamic. /** * @displayname Abstract Service * @hint I provide common persistence functionality */ component { public void function init(){ throw(type="AbstractDAO",message="AbstractDAO is meant to be extended not instantiated"); } /** * @hint I will return a new instance of the entity we are working with */ public any function new(){ return entityNew(getEntity()); } /** * @hint I will find the entity name of the service that is extending this abstract service. * I will first look for the entity attribute of the component. If that is not found I will look at * the service name. If you follow this convention I can extract the name {Entity}Service. UserService = User entity */ private string function getEntity(){ var meta = getMetadata(this); var entity = ""; if(structKeyExists(meta,"entity")){ // get the meta data for the entity name entity = meta.entity; } else { // read the service name and extract the first part as the entity name if(structKeyExists(meta,"fullname")){ var service = listLast(meta.fullname,"."); entity = replaceNoCase(service,"dao",""); } } return entity; } } Now we have the foundation and we can start building out our methods. Next up I am going to create a load method that accepts an id. If no id is passed then we will return a new object. /** * @hint I will load an object based on an id. If you pass nothing I will return a new object */ public any function load(Numeric id=0){ if(arguments.id == 0){ return new(); } else { var obj = EntityLoadByPK(getEntity(),arguments.id); return obj; } } Next we can create our list method. I don't know about you but when I think of listing rows from a database I think query. My list method will by default always return a query object. You can pass asquery = false to get an array of objects. At a later time we will look at different ways to pass more criteria to this method but for now we will keep it simple. /** * @hint I am a generic list function. I have the same arguments as entityLoad but by default I will return a query */ public any function list(Struct filter=structNew(),String sortorder="",Struct options=structNew(),Boolean asquery=true){ var rows = EntityLoad(getEntity(),arguments.filter,arguments.sortorder,arguments.options); if(arguments.asquery){ return entityToQuery(rows); } return rows; } Our save and delete methods are pretty straight forward. /** * @hint I will save an object */ public void function save(obj){ EntitySave(arguments.obj); } /** * @hint I will delete an object */ public void function delete(obj){ EntityDelete(arguments.obj); } Which brings me to my favorite method, the findByDynamically. This was inspired by grails and a post I found by Joe Rinehart. This allows us to dynamically find any methods. For example our authors table has a firstname and lastname property. Using this method we could make the following method call and it would return us the record. <cfset author = application.Author.findByFirstNameAndLastName("Mike","Murdock")> <cfdump var="#author#"> The other "dynamic" feature I want to use in this method is the ability to return a query. When your searching for multiple fields your most likely going to bring back 1 record. In another scenario like the following I am going to get back many records, so it makes more sense to return a query. That's right, to get a query back just append asquery (case does not matter). <cfset authors = application.Author.findByIsSpotlightAsQuery("N")> <cfdump var="#authors#"> To accomplish this we are going to use the onMissingMethod function. First we check to see if we are returning the result as a query. Next if the first 6 characters of the name is findby we can assume its probably something like findByXYZ or findByXAndY. public any function onMissingMethod(String missingMethodName,Struct missingMethodArguments){ var name = arguments.missingMethodName; var args = arguments.missingMethodArguments; var asquery = false; // if asquery is found mark the return and strip it from the name if( lcase(right(name,7)) == "asquery" ) { asquery = true; name = replaceNoCase(name,"asquery",""); } if(lcase(left(name,6)) == "findby"){ var rows = findByDynamically(name,args); } // you can always get a query bck by appending AsQuery if( asquery ) { return entityToQuery(rows); } else { return rows; } } The findByDynamically method is now called and works its magic. There are a couple of other private methods that you can check out in the download that help build our where clause but they are explained pretty well so check out the attached source code. private any function findByDynamically(String name,Struct params){ var where = replaceNoCase(arguments.name,"findby",""); var fields = buildWhereClause(where); var filter = {}; for(i=1; i <= listLen(fields); i++){ filter[listGetAt(fields,i)] = arguments.params[i]; } return entityLoad(getEntity(),filter); }

Complete AbstactDAO component. /** * @displayname Abstract Service * @hint I provide common persistence functionality */ component { public void function init(){ throw(type="AbstractDAO",message="AbstractDAO is meant to be extended not instantiated"); } /** * @hint I will return a new instance of the entity we are working with */ public any function new(){ return entityNew(getEntity()); } /** * @hint I will load an object based on an id. If you pass nothing I will return a new object */ public any function load(Numeric id=0){ if(arguments.id == 0){ return new(); } else { var obj = EntityLoadByPK(getEntity(),arguments.id); return obj; } } /** * @hint I am a generic list function. I have the same arguments as entityLoad but by default I will return a query */ public any function list(Struct filter=structNew(),String sortorder="",Struct options=structNew(),Boolean asquery=true){ var rows = EntityLoad(getEntity(),arguments.filter,arguments.sortorder,arguments.options); if(arguments.asquery){ return entityToQuery(rows); } return rows; } /** * @hint I will save an object */ public void function save(obj){ EntitySave(arguments.obj); } /** * @hint I will delete an object */ public void function delete(obj){ EntityDelete(arguments.obj); } /** * @hint I will return the total number of records this entity contains */ public numeric function count(){ return ormexecutequery("select count(*) from " & getEntity(),true); } public any function onMissingMethod(String missingMethodName,Struct missingMethodArguments){ var name = arguments.missingMethodName; var args = arguments.missingMethodArguments; var asquery = false; // if asquery is found mark the return and strip it from the name if( lcase(right(name,7)) == "asquery" ) { asquery = true; name = replaceNoCase(name,"asquery",""); } if(lcase(left(name,6)) == "findby"){ var rows = findByDynamically(name,args); } // you can always get a query bck by appending AsQuery if( asquery ) { return entityToQuery(rows); } else { return rows; } } /** * @hint I will find the entity name of the service that is extending this abstract service. * I will first look for the entity attribute of the component. If that is not found I will look at * the service name. If you follow this convention I can extract the name {Entity}Service. UserService = User entity */ private string function getEntity(){ var meta = getMetadata(this); var entity = ""; if(structKeyExists(meta,"entity")){ // get the meta data for the entity name entity = meta.entity; } else { // read the service name and extract the first part as the entity name if(structKeyExists(meta,"fullname")){ var service = listLast(meta.fullname,"."); entity = replaceNoCase(service,"dao",""); } } return entity; } /** * @hint I am a dynamic find by method and I can only be called locally */ private any function findByDynamically(String name,Struct params){ var where = replaceNoCase(arguments.name,"findby",""); var fields = buildWhereClause(where); var filter = {}; for(i=1; i <= listLen(fields); i++){ filter[listGetAt(fields,i)] = arguments.params[i]; } return entityLoad(getEntity(),filter); } /** * @hint I will search fields for the word AND. If I find and I will grab the left * and right side to see if they are valid properties, if they are then we have a join. * If we do not it could be that our field name has and in it such as Candidate or standard. */ private string function buildWhereClause(String fields){ var fieldList = arguments.fields; if(findNoCase("AND",arguments.fields)){ // make sure the AND we found was not part of a field name var join = replaceNoCase(arguments.fields,"AND",","); var f1 = listFirst(join); var f2 = listlast(join); // if the left and right side of AND are valid properties if(isValidProperty(f1) && isValidProperty(f2)){ // we found an actual And statement and not a property fieldList = replaceNoCase(arguments.fields,"AND",",","all"); } } return fieldList; } /** * @hint I will take a prperty name and compare it against the acutally property list of the entity */ private boolean function isValidProperty(String property){ var properties = arrayToList(getProperties()); var exists = false; if(listFindNoCase(properties,arguments.property)){ exists = true; } return exists; } /** * @hint I will return an array of the property names for this entity */ private array function getProperties(){ var entity = getEntity(); var properties = ormGetSessionFactory().getClassMetaData(entity).getPropertyNames(); return properties; } }

In closing I could of went into way more depth here but I wanted to start out with some simple examples. Please download the attached demo and check out the code. I have many other methods in my abstract dao and I will share those soon. For now I would love your feedback / suggestions.

This entry was posted on January 6, 2010 at 10:28 PM and has received 4288 views. Comments 4 | Print this entry. Download attachment.