Consider this CFC Person.cfc

/**
 * @accessors true
 */
Component Person{
    property firstname;
    property lastname;
    property age;
    property city;
    property state;
}

When an object is created for this CFC, you can directly call the setters and getters for the properties as

<cfscript>
    person = new Person();
    person.setFirstName("Brad");
    person.setLastName("Pitt");
    person.setAge(46);
 
    writeOutput("Name : #person.getFirstName()# #person.getLastName()#");
    writeOutput("Age : #person.getAge()#"); 
</cfscript>

The implicit setter/getter uses the ‘variable’ scope, which is a private scope for a object, for storing the data. i.e the setter method puts the data in the variable scope and the getter method gets the data from the variable scope.

What if you want to override the setter/getter method? Ofcourse you can do that. You just need to define those methods in your CFC and ColdFusion will call your method instead of calling the implicit one.

Hmm.. What if you dont want ColdFusion to generate getter or setter or both methods for a particular property? You can disable that by adding attribute getter=”false” and setter=”false” on the property.

So if you define a property

property name="city" getter="false" setter="false";

ColdFusion will not generate getCity() and setCity() methods for this CFC.

The implicit methods can also do some nice validation if you have given the ‘type’ for properties. Consider the same Person.cfc with type specified where we have made age as a numeric type.

/**
 * @accessors true
 */
Component Person{
    property string firstname;
    property string lastname;
    property numeric age;
    property string city;
    property string state;
}

ColdFusion will do the datatype validation whenever the setter method is called for any property. So if you call

<cfscript>
    person = new Person();
    person.setFirstName("Brad");
    person.setLastName("Pitt");
    person.setAge("LA");
</cfscript>

It will throw a nice error saying “The value cannot be converted to a numeric”.

Whats more interesting is that you can do a whole lot of validation using cfproperty. We have added two more attributes on cfproperty named ‘validate’ and ‘validateparams’. These attributes allow you do even more advanced validations of the property data when the setter method is called for a property. (This is similar to cfparam or cfform validation).

The possible values for validate attributes are

• string

• boolean

• integer

• numeric

• date

• time

• creditcard: A 13-16 digit number conforming to the mod10 algorithm.

• email: A valid e-mail address.

• eurodate: A date-time value. Any date part must be in the format dd/mm/yy. The format can use /, -, or . characters as delimiters.

• regex: Matches input against pattern specified in validateparams.

• ssn: A U.S. social security number.

• telephone: A standard U.S. telephone number.

• UUID: A Home Universally Unique Identifier, formatted ‘XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXX’, where ‘X’ is a hexadecimal number.

• guid: A Universally Unique Identifier of the form “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” where ‘X’ is a hexadecimal number

• zipcode: U.S., 5- or 9-digit format ZIP codes

The ‘validateparams’ attribute available with <cfproperty> takes the parameters required by the validator specified in the ‘validate’ attribute. This needs to be specified in the implicit struct notation.

• min: Minimum value if ‘validate’ is integer/numeric/

• max: Maximum value if the ‘validate’ is integer/numeric/

• minLength: Minimum length of the string if the ‘validate’ is string

• maxLength: Maximum length of the string if the ‘validate’ is string

• pattern: regex expression if the validator specified in ‘validate’ attribute is regex

Consider the Person again where we will add few more properties with some validation

/**
 * @accessors true
 */
Component Person{
    property string firstname;
    property string lastname;
    property numeric age;
    property string city;
    /**
     * @validate string
     * @validateparams {minLength=2, maxLength=2}
     */
    property string state;
    /**
     * @validate zipcode
     */
    property numeric zip;
    /**
     * @validate telephone
     */
    proeprty phone; 
}

Now when you create an object of Person and call setState(state), before setting the data for state in variable scope, ColdFusion will validate that state value provided is of type ’string’ and its length is 2. Similarly setZip() will validate that the input data is a valid zip code and setPhone() will validate that the input data is a valid telephone number.

For String type properties, you can also do regular expression validation allows you to have all sort of validation on a property of string type.

And to top it all, all of these nice goodies are available to you at a much lesser cost than regular UDFs. Yes, you read it right. Implicit methods perform much better than regular UDFs that you write in CFC. To confirm that, lets use this CFC where we will use implicit methods for ‘firstName’ and write our own accessors for ‘lastName’.

/**
 * @accessors true
 */
component 
{
    property String firstName;
    lastName = "";
 
    public void function setLastName(string name)
    {
        lastName = name;
    } 
 
    public string function getLastName()
    {
        return lastName;
    }
}

Both implicit methods and UDFs are doing exactly the same thing i.e settings and getting the data in/from variable scope. Now lets run this comparison test

<cfscript>
    person = new Person();
    t = getTickCount();
    for(i = 0; i &lt; 100000; i++)
    {
        person.setfirstName("Brad");
        fname = person.getFirstName();
    }
    writeOutput("Total Time in implicit methods " & (getTickCount() - t));
    t = getTickCount();
    for(i = 0; i &lt; 100000; i++)
    {
        person.setLastName("Pitt");
        lname = person.getLastName();
    }
    writeOutput("Total Time in UDF methods " & (getTickCount() - t));
</cfscript>

Here is the output

Total Time in implicit methods 63
Total Time in UDF methods 485

Thats almost eight times faster than regular UDF. Isn’t that sweet? You get those auto-generated methods, whole lot of auto-magical validations and to top that, incredible performance. I am sure writing accessors for your CFC fields will become a thing of past now !

Update : Post public beta, we have disabled implicit getters/setters for non-persistent CFC. To enable it, you need to set “accessors=’true’” on the component. For persistent CFC, the implicit getters/setters will always be enabled. I have changed the examples above to reflect this.

You can download the plugin from here and download the instruction from here. Have Fun playing with it !!!

It is true that CFC performance is poor as compared to POJO and it will always be. ColdFusion CFC has lot of cost involved because of the dyanmic nature of it and additionally, it has reflection cost involved. I had shared some of the reasons with few of the community members and I thought it will be interesting to share it with a wider audience. Here are the main reasons :

1. Unlike java where the class has a fully qualified name and is loaded only once in the classloader, when you create CFC, CF needs to search for the CFC file on the disk, compute the class name for it and then load it. And that happens on each object creation unless you have switched on trusted cache .
2. CFC  is compiled at runtime, loaded and constructed using reflection. I am sure you will be aware that reflection is much slower (25 times easily) than direct invocation in java.
3. CFC has two different scopes – this and variables scope which is a struct. So every object creation involves two additional struct creation cost.
4. CFC creation also involves running the default constructor i.e any code outside cffunction and that happens for each object creation. That involves the complete setup for method invocation i.e setting up localscope, superscope etc (another two structs here), which is also significant
5. CFC allows UDFs to be added/removed from the object at runtime and hence methods are added to each object on object creation and that too in both the scopes (adding each UDFs in both the scopes also has significant cost). Thats the reason why object creation becomes costlier as you add methods in the CFC. Higher the number of methods, higher the object creation cost.

We have done a lot of performance improvements regarding CFC creation and invocation in ColdFusion 9 which I hope you would have noticed. But even then it can not match POJO performance and thats an unrealistic target.

So given that, lets come to the question – How much does CFC creation performance matters when it comes to ORM. In reality, not much. We have done a number of performance comparison between CFC and POJO with hibernate keeping everything else absolutely same. And all the time, CFC performance was same or better than POJO persistence. It might sound unbelievable and in fact I also could not believe it myself when I saw the performance numbers first. But that is the truth. And here is why it happens – When it comes to persistence, the time taken in DB operation and the persistence layer is much more than the time taken in object creation. And that cost is same for POJO and CFC. So the only difference in cost between CFC and POJO with respect to ORM is object creation cost and cost of populating/fetching the properties data. For instantiating POJO object and for using properties accessors, Hibernate has to use reflection which is always costly and that removes this cost difference of CFC and POJO. And for few of the runs, CFC was able to beat POJO as well and explanation for that is the optimizations that we have done in using accessors for properties.

I would be curious to know about your experience regarding CF-ORM performance and CFC performance in general. How has your experience been so far regarding CF-ORM peformance?

ORM is object relational mapping and in ColdFusion, objects are created using CFC. CFCs that needs to be persisted are called persistent CFC and that is marked by setting ‘persistent’ attribute to true on the component. We also need to define what persistent fields will be there in a persistent CFC and that is defined using ‘cfproperty’. A field/property is marked persistent by setting persistent attribute to true on the cfproperty. By default, if the CFC is persistent, all its properties are considered as persistent unless you mark a property non-persistent. So typically ‘persistent’ attribute on the property is used only when you need to make that property non-persistent.

Each persistent CFC in ColdFusion application maps to a table in the database and each property in the persistent CFC maps to a column in the table (not exactly true but we will come to that later.. For the time being lets keep it that way). We will use the cfartgallery datasource for this example which has Artists and Art tables.

The first thing you need to do is – enable ORM for the application and define a datasource to be used (What is an ORM without a datasource?). ColdFusion ORM uses Application.cfc to define all the ORM specific settings. (If you haven’t started using Application.cfc for your application, its time to start using it!)

Application.cfc

Component {
    this.name="ArtGallery";
    this.ormenabled="true";
    this.datasource="cfartgallery";
}

Note that the datasource setting defined here makes it the default datasource of your application which can be used by tags like cfquery, cfinsert, cfupdate, cfdbinfo. The same default datasource will be used by ORM as well.

There are a whole bunch of ORM related configuration that you can do in application.cfc which you can refer here.

Now that the application is configured, let us build the object and define the persistence information on it. To start with, we will first define the Artist.cfc

Artists.cfc

/**
 * @persistent
 */
Component {
    property name="artistid" generator="increment";
    property firstname;
    property lastname;   
    property address;
    property city;
    property state;
    property postalcode;
    property email;
    property phone;         
    property fax;
    property thepassword;
}

This is the most simplistic definition of the component where we have defined only the component and its properties names. Since the table for this CFC already exists in the database, we have not added any table specific information in this and we will let ORM infer all the information from the database. The only additional setting that we have added here is the ‘generator’ attribute which is used to auto-generate the primary key.

After the components are defined, the first request to this application (i.e a page in this application) will make CF-ORM do all the setup necessary (basically generation of hibernate configuration, mapping files, building the session factory etc). Once the setup is done, you are all set to work with the entities.

We will first list all the artists and here is what you need to do for that

listAll.cfm

<cfscript>
   artists = EntityLoad("Artists");
   writedump(artists);
</cfscript>

To load a particular Artists with its ID, here is what you do

 list.cfm

<cfscript>
   artist = EntityLoadByPK("Artists", 1);
   writedump(artist);
</cfscript>

There are several flavors of EntityLoad functions details of which can be read here

Let us now see how to perform insert and update on it.

save.cfm

1
2
3
4
5
6
7
8
9
10
11

<cfscript><br>   // Insert a new artist
   artist = new Artists();
   artist.setfirstname("Leonardo");
   artist.setlastname("Da vinci");
   artist.setcity("Paris");
   EntitySave(artist);
 
   writeOutput(artist.getartistid());// Update an artist
   artist = EntityLoadByPK("Artists", 2);
   artist.setcity("NewYork"); // artist is automatically updated.
</cfscript>

As we see in the above example, EntitySave is used to insert/update an object in the table. There are some important things to note here

• EntitySave is an intelligent function which automatically finds if a new row needs to be inserted for the given object or whether an existing row needs to be updated.
• We called EntitySave for the insert here but not for update but even then artist ‘2′ gets updated. So how did that happen? Actually what happens here is when you load an artist object, it becomes associated with the hibernate session which keeps track of any changes in the object and automatically saves it when the session is flushed. We will talk about more about hibernate session in a later post. For the time being lets just say that Hibernate Session is a short-lived object that represents a conversation between the application and the persistence layer and also acts as the first level of cache.
• We did not write any setter or getter method for artist’s properties in Artists.cfc but we are calling them here. That works because ColdFusion 9 automatically generates accessor methods for any property written in a CFC. More details on generated methods in a later post.
• At line no 6, we called entitySave, but if you check the database, the row is not inserted yet. So when does that happen? Hibernate batches up all the operations till the end of the request or to be exact till hibernate session is flushed. ColdFusion ORM starts up a session when the first ORM method is called in the request and is automatically flushed when the request ends. The batching is done for performance reason so that hibernate executes the sql with the final state of the objects. It will be a huge performance bottleneck if ORM keeps executing sql for each changes in the object.

To delete an Artist, you need to call EntityDelete() passing the object to be deleted.

delete.cfm

<cfscript>
    artist = EntityLoadByPK("Artists", 15, true);
    EntityDelete(artist);
</cfscript>

Relationship

So far we have seen how to perform CRUD for a single entity. But in any application, there will be entities which are associated and ORM must load the associated object as well when loading a particular entity. For our example, an Art will have an Artist and when loading the art object, it should also load the associated artist. So lets build the model first after which we will see how to work with the association.

In cfartgallery, the table Artists has a one-to-many relationship with Art table, which are joined using the foreign key column ARTISTSID. This means that each artist has created multiple arts and each art is created by one artist. To represent this in the object model, each ARTIST object would contain an array of ART objects. Each ART object will also contain a reference to its ARTIST object thereby forming a bidirectional relation.

To achieve this, we will need to add an extra property ‘arts’ to ‘Artists’ that contains an array of ART objects for that Artist. The modified Artists.cfc would look like

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

/**
 * @persistent
 */
Component {
    property name="artistid" generator="increment";
    property firstname;
    property lastname;   
    property address;
    property city;
    property state;
    property postalcode;
    property email;
    property phone;         
    property fax;
    property thepassword;
    property name="arts" fieldtype="one-to-many" fkcolumn="artistid" cfc="Art" cascade="all" inverse="true";
}

Here is the Art.cfc

1
2
3
4
5
6
7
8
9
10
11
12

/**
 * @persistent
 */
Component {
    property name="artid" generator="increment";
    property artname;
    property price;
    property largeimage;
    property mediaid;
    property issold;
    property name="artist" fieldtype="many-to-one" fkcolumn="artistid" cfc="Artists" ;
}

Notice the artist property above which is of many-to-one type. Also notice that both the property use the same value for fkcolumn attribute i.e ‘artistid’ of Art table that references artistID pk of Artist table.

Since we have added a new persistent CFC (Art.cfc) after the application was loaded, we need to re-initialize the ORM for this application so that mappings for Art.cfc also gets generated. This can be done by calling ORMReload() method. There are some nice ways to do this but for the time being lets keep it simple by putting this in a separate page which we will call to reload ORM.

initializeORM.cfm

<cfset ormReload()>

If you load and dump Artist (using listAll.cfm), you should also see the associated art objects for artists.

Now let us create a new Art and associate it with an existing Artist.

artCreate.cfm

1
2
3
4
5
6
7
8
9
10

<cfscript>
    artist = EntityLoad("artists", 1 ,"true");
    art = new Art();
    art.setartname("landscape");
    art.setPrice(1500);
    art.setissold(false);
    art.setartist(artist);
    artist.addArts(art);
    EntitySave(art);
</cfscript>

If you notice line 7-8 above, we associate artist to art by calling art.setArtist(artist) as well as art to artist by calling artist.addArts(art). Hibernate needs us to do this in order to set up the bidirectional relation properly. Since it is a bidirectional relation, you must also decide which side will set the relation in the database. i.e which side of the relation will set the fkcolumn in the table. This is controlled by the “inverse” attribute of proeprty, which if set to true, tells hibernate that this is a inverse of the other relation and this side of relation should be ignored for persistance. If you don’t set inverse to true, Hibernate will unnecessarily fire two sqls for the same association.

So there you have it. We have seen how you can use ORM to perform the basic CRUD operations on entities. For more details, you can refer to the ORM doc and Hibernate docs.

Ben talked about the new features in ColdFusion 9 and ColdFusion beta here :

http://www.adobe.com/devnet/coldfusion/articles/coldfusion9_whatsnew.html

http://www.adobe.com/devnet/coldfusion/articles/cfbuilder_whatsnew.html

Here are the links for public beta

ColdFusion 9 : http://labs.adobe.com/technologies/coldfusion9/

ColdFusion Builder : http://labs.adobe.com/technologies/coldfusionbuilder/

I also wanted to highlight an excellent devnet article written by Mark Mandel introducing ColdFusion ORM. I am sure ColdFusion ORM is going to completely change the way ColdFusion applications are built and is going to make you much more productive. Hey, I am not boasting because its my baby, but I genuinely feel this