Manju's blog » ORM

ColdFusion-ORM: Auto-generation of tables, Naming Strategy and automatically populating data

Manjukiran — Fri, 09 Oct 2009 12:39:00 +0000

Task:
Example to demonstrate Auto-generation of tables, Naming strategy and automatically populating data in ColdFusion-ORM

Stuff that you would learn:
- To auto-generate tables in ORM
- To fill data into the auto-generated tables
- To use the DDL-only attributes
- To define custom Naming Strategy

Steps to Run the example:
- Create a datasource by name ‘test_datasource’ pointing to a empty database. Note that the example will take care of creating the tables and populating data into it.
- Create a directory say "orm_autogen" under webroot.
- Create the following files – Application.cfc, Art.cfc, Artists.cfc, mysqlscript.sql, lcasestrategy.cfc and index.cfm.
- Run the URL “http://:/orm_autogen/index.cfm”

Application.cfc

Art.cfc

Artists.cfc

lcasestrategy.cfc

mySQLScript.sql

--This SQl script will be automatically executed after the tables are auto-generated.
--Note that each SQL should be separated by a ';'.
insert into Artists(artistid, firstname, lastname, address, city, state, postalcode, email, phone, fax, thepassword)
values(1, 'Aiden', 'Donolan', '352 Corporate Ave.', 'Denver', 'CO', '80206-4526', 'aiden.donolan@donolan.com', '555-751-8464', '555-751-8463', 'peapod');
insert into Artists(artistid, firstname, lastname, address, city, state, postalcode, email, phone, fax, thepassword)
values(2, 'Austin', 'Weber', '25463 Main Street, Suite C', 'Berkeley', 'CA', '94707-4513', 'austin@life.com', '555-513-4318', '510-513-4888', 'nopolyes');
insert into Art(artname, price, largeimage, mediaid, issold, artistid)
values('Michael', 13900, 'aiden02.jpg', 1, 0, 1);
insert into Art(artname, price, largeimage, mediaid, issold, artistid)
values('Space', 9800, 'elecia01.jpg', 2, 1, 2);

index.cfm

Speaking on ‘ColdFusion 9: Advance ORM’ at CFUnited 2009

Manjukiran — Thu, 23 Jul 2009 17:33:34 +0000

I am excited to say that I will be speaking on ColdFusion 9: Advanced ORM at CFUnited – on August 13th at 3:15PM. Terry Ryan will cover the basics of ORM in an other session just before mine. I am planning to cover the following as part of the talk:

Relationship – one-to-many, many-to-one, one-to-one and many-to-many
Event Handling
Lazy Loading
Caching
Transactions
ORM Session Management
HBM files
Development time support – ormreload(), logSQL, savemapping, etc
Generating DDL

If you want me to cover any other topics, do comment about it(Note that the above list is tentative. ORM is a vast subject and I need to consider the time factor as well.) This is my second session in CFUnited. Last year I had talked about Taking advantage of 64-bit support in ColdFusion.

Details about the other sessions from Adobe speakers is here. Meet you all at CFUnited!

ColdFusion-ORM: Define Computed properties (formula attribute)

Manjukiran — Fri, 17 Jul 2009 19:43:00 +0000

What are computed properties?
Consider the tables – Art and Artists. Art and Artists form a one-to-many relationship where one Artist has created many Art. Say, in each Artist object, you need a property that would contain the number of arts made by the Artist – use computed properties. The formula to compute the value of the property should be specified using the formula attribute of the cfproperty tag. The formula should be specified as a SQL that returns a single value. Note that computed properties do not map to any column in the table and are not persistent.

Task:
Example to demonstrate using computed properties in ColdFusion-ORM

Stuff that you would learn:
- how to define computed properties
- how to define the formula for computed properties

Steps to Run the example:
- This example needs the cfartgallery datasource. This is shipped with ColdFusion by default.
- Create a directory say "ormformula" under webroot.
- Create the following files – Application.cfc, Artists.cfc and index.cfm.
- Run the URL “http://:/ormformula/index.cfm”

Application.cfc

component
{
    //Name of the application
    this.name = "ORM_Formula";

    //ormenabled should be set to true so that ORM is enabled for this application
    this.ormenabled = "true";

    //Set the datasource that needs to be used by the ORM Functions.  You can also set this in the ormsettings struct
    this.datasource = "cfartgallery";
}

Artists.cfc

component persistent="true" entityname="Artists" table="Artists"
{
    property name="id" column="ARTISTID" generator="increment";
    property name="firstname";
    property name="lastname";
    property name="address";
    property name="city";
    property name="state";
    property name="postalcode";
    property name="email";
    property name="phone";
    property name="fax";
    property name="thepassword";
    /*
        A property automatically becomes a computed property if formula attribute is specified.
        A SQL that returns a single value should be input to the formula attribute.  Note
        that computed properties do not map to any column in the table and are not persistent.

        In this example, the "numberOfArts" property will store the number of arts made by the
        Artist.  

        Have a close look at the SQL that is used. In this SQL, if you specify any column name, by default,
        hibernate assumes that the column is from the table to which this CFC maps to - here
        Artists table.  If you want to specify a column that belongs to another table, you should alias
        them. Hence, here, in the where condition art.ArtistId=ArtistId, the latter 'ArtistId' would be
        from the Artists table.  For each Artists entity, Hibernate would then substitue 'ArtistId' with
        the column-value for that entity.  For example, for the entity with ArtistId=5, the SQL would be:

            select Count(*) from Art art where art.ArtistId=5
    */
    property name="numberOfArts" formula="select Count(*) from Art art where art.ArtistId=ArtistId";
}

index.cfm








    
        #artist.getFirstName()# #artist.getLastName()# has #artist.getNumberOfArts()# arts

ColdFusion ORM: ORM-CFC Generator Extension for Adobe ColdFusion Builder

Manjukiran — Fri, 17 Jul 2009 11:09:00 +0000

When we started working on ColdFusion-ORM feature (me and Rupesh), the only way to provide ORM mapping was by using the hibernate XML file (hbm.xml). Later, we provided a way to specify the mapping in CFCs – ColdFusion-ORM would then take care of creating the hibernate mapping. This made life easier for the ColdFusion developers. Now we have the ORM-CFC Generator Extension in Adobe ColdFusion Builder which will generate ORM-CFCs automatically!

The Adobe CFC Generator can be downloaded from this location and the instructions to use it are here. The Adobe CFC Generator

allows you to create ORM-CFCs from a set of tables.
allows you to configure the ORM-CFCs – change the CFC-Name, change EntityName, change property-name, select/de-select columns, add relationships and join-conditions, etc.
generates ORM-CFCs (of-course!)
generates Service CFCs for each ORM-CFC that contain certain utility methods to work with the ORM-entities

Note that the Adobe CFC Generator is provided as a sample extension. When the extension is installed, the source-code for the extension can be found in the installed location. Using the source code, you can modify/customize the UI/ORM-cfcs/Service-cfcs to add additional functionality.

Check out this blog post – How Do I generate ORM CFC’s??? – A nice captivate demo which shows you how to install and use ORM-CFC Generator Extension. The CFBuilder team will be posting heavily on extensions in the coming days – do have an eye on that space.

ColdFusion-ORM: Collections

Manjukiran — Thu, 16 Jul 2009 18:27:00 +0000

In this post, I will digress a bit and introduce you to a lighter feature of ColdFusion-ORM – COLLECTIONS.

What are collections?
Consider the same tables we have been using – Art and Artists. Say, in the Artist object, you just need an array/struct of Art names instead of an array/struct of the Art objects, then use collections.

Task:
Example to demonstrate collections in ColdFusion-ORM

Stuff that you would learn:
- how to create a collection as an array
- how to create a collection as a struct
- how to create a sorted collection

Steps to Run the example:
- This example needs the cfartgallery datasource. This is shipped with ColdFusion by default.
- Create a directory say "ormcollections" under webroot.
- Create the following files – Application.cfc, Artists.cfc and index.cfm.
- Run the URL http://localhost:8500/ormcollections/index.cfm

In this example, I have put comments only in Artsists.cfc. Please read the previous posts if need information about the other files.

Application.cfc

component
{
    //Name for the application
    this.name = "ORM_Collections";

    //ormenabled should be set to true so that ORM is enabled for this application
    this.ormenabled = "true";

    /*
    Set the datasource that needs to be used by the ORM Functions.
    You can also set this in the ormsettings struct
    */
    this.datasource = "cfartgallery";
}

Artists.cfc


component persistent="true"
{

    property name="artistid" generator="increment";
    property name="firstname";
    property name="lastname";
    property name="address";
    property name="city";
    property name="state";
    property name="postalcode";
    property name="email";
    property name="phone";
    property name="fax";
    property name="thepassword";

/*
Artists have many arts.  Using Collections, the name of the arts created by
each artist can be retrieved as a string array.  Note that the art names
is picked from the table and you don’t require the ART component.  This also means
that you get an array of strings and not an array of persistent objects.

For doing this, first of all, set fieldtype="collection".

type: can be "array" or "struct". Defaults to array.  If type=array, the art
names are retrieved as an array of names.  If type=struct, the art names are
retrieved as key-value pairs.

table: The name of the table in which the collection needs to be retrieved from.

fkcolumn: The name of the foriegn key. If not specified, will be figured
out by inspecting the database.

elementcolumn: The name of the table column which should be the retrieved as
the values of the array/struct. In this case, the names of the arts (Art->artname).

elementtype: The datatype of the table column used in elementcolumn.

orderby: Specify the sort order.  The string should be specified in the format
" ,  , ...". 
should be the name of the column name of the table.  is "desc" or "asc".
*/

    property name="ArtNamesAsArray" fieldtype="collection" table="Art"
    fkcolumn="artistid" type="array" elementtype="string" elementcolumn="artname"
    orderby="artname desc";

/*
Here is one more property which retrieves artnames but it retrieves it as a struct.

Two additional attributes are requried to defined for this collection type - structkeycolumn and
structkeytype in addition to the attributes used for fieldtype="collection" for type="array".

Structkeycolumn: Specify the column name of the table which should be used for the keys of the struct.
This column should be unique for the records that are retrieved. Here, the column artid is used.  

Structkeytype: The type of the column that is used in structkeycolumn.
*/

    property name="ArtNamesAsStruct" fieldtype="collection" table="Art" fkcolumn="artistid"
    type="struct" elementtype="string" elementcolumn="artname" structkeytype="int"
    structkeycolumn="artid" orderby="artid";
}

index.cfm




    /*
      Load the artists
    */
    artists = EntityLoad("Artists");

    WriteOutput("Display the Artist name and the name of their arts which we got as an array
");

    for (i=1;i<=ArrayLen(artists);i++)
    {
        artist = artists[i];

        /*Retrieve the Names of the Arts created by the artist
          The Art-Names are retrieved as an array
        */
        artNameArray = artist.getArtNamesAsArray();

        /*
          Display the Artist Name and their arts
        */
        WriteOutput("" & artist.getFirstName() & " " & artist.getLastName() & " has created ");
        if (ArrayLen(artNameArray))
        {
            for (j=1;j<=ArrayLen(artNameArray);j++)
            {
                WriteOutput('' & artNameArray[j] & ', ');
            }
        }
        else
        {
            WriteOutput("none");
        }
        WriteOutput("
");
    }
    WriteOutput("
");
    /*
      In the above section, retrieving art names as a array is shown.  The following section retrieves the
      art names as a struct
    */
    WriteOutput("Display the Artist name and his arts which we got as struct
");

    for (i=1;i<=ArrayLen(artists);i++)
    {
        artist = artists[i];

        /*
          Retrieve the names of arts.  The Art Names are retrieved as a struct
          The keys of the struct are the IDs of the respective arts.
        */
        artNameStruct = artist.getArtNamesAsStruct();

        /*
        Display the Artist Name and their arts.
        */
        WriteOutput("" & artist.getFirstName() & " " & artist.getLastName() & " has created ");
        artNameKeyArray = StructKeyArray(artNameStruct);
        if (ArrayLen(artNameKeyArray))
        {
            for (j=1;j<=ArrayLen(artNameKeyArray);j++)
            {
                /*
                  Art ID is a integer.  Hence using the java method to retrieve the value of the struct member
                */
                WriteOutput('' & artNameStruct.get(javacast("int", artNameKeyArray[j])) & ', ');
            }
        }
        else
        {
            WriteOutput("none");
        }
        WriteOutput("
");
    }

ColdFusion-ORM: Define One-to-Many and Many-to-one relationships

Manjukiran — Wed, 15 Jul 2009 12:43:00 +0000

Task:
Example to demonstrate how to establish one-to-many and many-to-one Relationships in ColdFusion-ORM

Previous Related Posts:
Getting Started with ORM
ColdFusion-ORM: Using CRUD Functions

Stuff that you would learn:
- how to establish a One-to-Many relationship between 2 CFCs.
- how to establish a Many-to-One relationship between 2 CFCs.
- how to do CRUD operations with CFCs which have a relationship.
- how to use the implicit relationship methods added by ColdFusion.
- cascade insert and delete

Steps to Run the example:
- This example needs the cfartgallery datasource. This is shipped with ColdFusion by default.
- Create a directory say "1tonorm" under webroot.
- Create the following files – Application.cfc, Art.cfc, Artists.cfc and index.cfm.
- Run the URL http://localhost:8500/1tonorm/index.cfm

I have interspersed the example with a lot of comments. You can understand the concept by just following the comments starting with Application.cfc and then Artists.cfc and then Arts.cfc and then index.cfm.

Application.cfc

component
{
    //Name of the application
    this.name = "ORM_One2Many";

    //ormenabled should be set to true so that ORM is enabled for this application
    this.ormenabled = "true";

    //Set the datasource that needs to be used by the ORM Functions.
    this.datasource = "cfartgallery";
}

Artists.cfc

component persistent="true"
{
    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;

    /*
    Artists have many arts and henace they form a one-to-many relation. The idea is to have all
    the arts as an array of art objects in each Artists' object.

    Set fieldytpe="one-to-many".

    Specify CFC="Art" to convey that the relationship is with Art.cfc.

    fkcolumn="artistid" to specify the foreign key.  But this is not required if foreignkey constraint
    is defined in the database - ColdFusion-ORM will figure it out by inspecting the database.

    cascade="all-delete-orphan": "all" signifies that all the CRUD operations will be cascaded to the
    related objects. "delete-orphan" means that it will delete the orphan objects in the art array
    i.e. if i remove an art from the arts array, it is now an orphan as it has no artist associated
    with it and hence will be automatically deleted.

    Implit Methods:    When a one-to-many relationship is established, the following implicit methods are introduced
    into the artist object:
    void addart() - used to add a art object to the relationship.
    boolean removeart() - used to remove the art object from the relationship.
    boolean hasart() - to check if there are any art objects in the artist object.
    boolean hasart() - to check if the input art object is present in the artist object.

    singularname: Use this attribute to specify custom name to the above implicit methods.

    type=array: To retrieve the arts objects as an array.  If type="struct", then the arts objects are retrieved as
    key-value pairs.  structkeycolumn and structkeytype should be specified in addition to all the above attributes
    to retrieve arts as key-value pairs.

    inverse=true: In a bi-directional relationship like this, you should specify one of the side as the controlling side
    which will set the relationship.  Usually, in a one-to-many bi-directional relationship, the many-to-one side should
    be the controlling side.  To do that, set inverse=true on this side (one-to-many side).
    */
    property name="arts" type="array" fieldtype="one-to-many" cfc="Art" singularname="art" fkcolumn="artistid"
    inverse="true" cascade="all-delete-orphan";
}

Art.cfc

component persistent="true"
{
    property name="artid" generator="increment";
    property name="artname";
    property name="price";
    property name="largeimage";
    property name="mediaid";
    property name="issold";  

/*
  Many arts have an artist and hence form a "many-to-one" relation.

  To establish a "many-to-one" relation, set fieldytpe="many-to-one"

  Specify CFC="Artists" to convey that the relationship is with Artists.cfc.

  fkcolumn="artistid": Used to specify the foreign key.

  missingRowIgnored: If the value is true, and the row that is referenced by the foreign
  key is missing, it is treated as a null association.
*/
    property name="artist" fieldtype="many-to-one" fkcolumn="artistid"
    cfc="Artists" missingRowIgnored="true";
}

index.cfm



    ormreload();

    /*
        Display the existing records in Artists Table.
        This will display the artist and their arts.
    */
    WriteOutput("Initial state of the Artists and Art tables
");
    DisplayArtists();

    /*
        Create an artist object and 2 art objects
    */
    newArtist = new Artists();
    newArtist.setfirstname("Daniel");
    newArtist.setlastname("Richard");

    newArt1 = new Art();
    newArt1.setArtName("Champions");

    newArt2 = new Art();
    newArt2.setArtName("Isolate");

    /*
        Associate the Arts to the Artist.  Notice that the
        implicit-relationship method - addArt is called.
    */
    newArtist.addArt(newArt1);
    newartist.addArt(newArt2);

    /*
        The one-to-many relationship should be established from both
        the ends.  Hence set the Artist to the new Arts.
    */
    newArt1.setArtist(newArtist);
    newArt2.setArtist(newArtist);

    /*
        Save the new artist. Note that EntitySave will save the artist as
        well as the associated arts as well (cascade-insert)
    */
    EntitySave(newArtist);
    ormflush();

    /*
        Display the existing records to check whether insert succeeded.
    */
    WriteOutput("State of the Artists and Art tables after insert.  Notice that the new
                artist - Daniel Richard is added with his arts 'Champions' and 'Isolate'
");
    DisplayArtists();

    /*
        Remove newArt2 and add newArt3.  In a way, you are just modifying the 'arts' array.  Notice that
        we are using the implicit=relationship method - removeArt is called.
    */
    newArt3 = new Art();
    newArt3.setArtName("Holiday");
    newArt3.setArtist(newArtist);
    newArtist.addArt(newArt3);
    newArtist.removeArt(newArt2);
    ormflush();    

    /*
        Check if delete and update of art succeeded.
    */
    WriteOutput("State of the Artists and Art tables after Deleting/Updating his Arts.  Notice that
                    the art 'Isolate' is removed and the art 'Holiday' is added.
");
    DisplayArtists();

    /*
        Delete the Artist.  Note that EntityDelete will delete
        the Artist as well as the associated arts. (cascade-delete).
    */
    EntityDelete(newArtist);
    ormflush();

    /*
        Check if delete succeeded.
    */
    WriteOutput("State of the Artists and Art tables after deleting the Artist.
                Notice that the artist 'Daniel Richard' is deleted.  All his arts are also deleted!
");
    DisplayArtists();

    /*
        A Utility function to display artists and his arts
    */
    function DisplayArtists()
    {
        query1 = new Query();
        query1.setSQL("select ArtistID, firstname, lastname from Artists where ArtistID>10");
        WriteDump(query1.execute().getresult());

        query1.setSQL("select ArtID, ArtName, ArtistID from Art where ArtID>50");
        WriteDump(query1.execute().getresult());
    }

del.icio.us Tags: ColdFusion,ORM,Adobe

ColdFusion-ORM: Using CRUD Functions

Manjukiran — Tue, 14 Jul 2009 06:57:14 +0000

Previous Related Posts:
Getting Started with ORM

First of all, pardon me for posting this example – I could have easily clubbed these concepts with my first post: Getting Started with ORM. I promise that in my further posts, I will club more concepts into a single example (but still try to keep it simple).

Task:
Example that demonstrates the CRUD Functions in ColdFusion-ORM

Stuff that you would learn:
- To work with the CRUD Functions – EntityNew, EntityLoad, EntitySave, EntityDelete
- ormflush() function to force-commit ORM calls
- OrmExecuteQuery function to execute HQL
- Saving the mapping file

Steps to Run the example:
- This example needs the cfartgallery datasource. This is shipped with ColdFusion by default.
- Create a directory say “crudorm” under webroot.
- Create the following files – Application.cfc, CArtists.cfc and index.cfm.
- Run the URL http://localhost:8500/crudorm/index.cfm

I have interspersed the example with a lot of comments. You can understand the concept by just following the comments starting with Application.cfc and then CArtists.cfc and then index.cfm.

Application.cfc

component
{
    //Name of the application
    this.name = "ORM_CRUDExample";

    //ormenabled should be set to true so that ORM is enabled for this application
    this.ormenabled = "true";

    //Set the datasource that needs to be used by the ORM Functions.  You can also set this in the ormsettings struct
    this.datasource = "cfartgallery";

    /*
    ColdFusion-ORM uses hibernate as its under-lying engine.  ColdFusion-ORM generates
    the hbm.xml file which contains the hibernate mapping.  To save the hibernate mapping
    that is generated, you need to set savemapping flag to true.  In this case, CArtists.hbm.xml
    file will be generated in the same folder as that of the application.
    */
    this.ormsettings.savemapping="true";
}

CArtists.cfc
(I have not added any comments to this file. If you need to learn about the different attributes used here, refer the example Getting Started with ORM)

component persistent="true" entityname="Artists" table="Artists"
{
    property name="id" column="ARTISTID" generator="increment";
    property name="firstname";
    property name="lastname";
    property name="address";
    property name="city";
    property name="state";
    property name="postalcode";
    property name="email";
    property name="phone";
    property name="fax";
    property name="thepassword";
}

index.cfm




    ormreload();
    /*
    Load the Artist records to display them.  There are a number of
    variations to the EntityLoad method which will help you to retrieve
    the records the way you want. Refer the documentation for EntityLoad for details.
    */
    WriteOutput("Initial state of the table
");
    DisplayArtists(EntityLoad("Artists"));

    /*
    Create a new Artist object and set the properties. This will
    be inserted to the table in the next step.
    EntityNew function takes entityname as input and creates a
    fresh object of the entity.
    */
    newArtistObj = EntityNew("Artists");
    newArtistObj.setfirstname("John");
    newArtistObj.setlastname("Smith");
    newArtistObj.setaddress("5 Newport lane");
    newArtistObj.setcity("San Francisco");
    newArtistObj.setstate("CA");
    newArtistObj.setPostalCode("90012");
    newArtistObj.setphone("612-832-2343");
    newArtistObj.setfax("612-832-2344");
    newArtistObj.setemail("jsmith@company.com");
    newArtistObj.setThePassword("jsmith");

    /*
    Insert the new artist object that you just created.
    EntitySave will insert the newArtistObj into the database.
    EntitySave is used for both update and insert.  ColdFusion
    will smartly figure out whether it is an update or insert.  As we are
    sure that this is an insert operation, we set the secondparameter to "true".
    ColdFusion now will always do the insert operation.
    */
    EntitySave(newArtistObj, true);

    /*
    Call ormflush so that the Insert SQL runs immediately. If ormflush
    is not called, all the CRUD operations in this page will be flushed at
    the end of the request.
    */
    ormflush();

    /*
     Display the artist records now to check if the new record got added.
     This time I have used a different function to retrieve the Artist records.
     This is just to introduce you to the ORMExecuteQuery set of functions.
     ORMExecuteQuery takes HQL as input and returns one-entity/array-of-entities/
     string/array-of-strings depending on the HQL.  HQL is the query language used
     in hibernate to retrieve objects based on complex joins.  This function has
     a number of overloads.  Please refer the documentation for more details.
    */
     WriteOutput("After adding the new record (Notice the Record with FirstName John being added)
");
     DisplayArtists(ORMExecuteQuery("from Artists"));

    /*
    Update the new Artist record.  Change the Phone number.
    You dont need to call EntitySave method here as the newArtistObj is
    an entity maintained by ORM.  Hence the updates to this entity will be automatically committed.
    */
    newArtistObj.setphone("612-832-1111");
    ormflush();

    /*
    Display the Artist records now to check if the new record got updated.
    */
    WriteOutput("After updating the new record (Notice the phone number with FirstName John updated)
");
    DisplayArtists(ORMExecuteQuery("from Artists"));

    /*
    Delete the record.  Also call ormflush so that the Delete SQL gets run immediately
    */
    EntityDelete(newArtistObj);
    ormflush();

    /*
    Display the Artist records now to check if the new record that was added, got deleted
    */
    WriteOutput("After deleting the new record (Notice the Record with FirstName John deleted)
");
    DisplayArtists(ORMExecuteQuery("from Artists"));





    
        
        
        
            ID
            NAME
            ADDRESS
            PHONE
            FAX
            EMAIL
        
        
            #artistsObj.getid()#
            #artistsObj.getfirstname()# #artistsObj.getlastname()#
            #artistsObj.getaddress()# #artistsObj.getCity()# #artistsObj.getState()# #artistsObj.getPostalCode()#
            #artistsObj.getphone()#
            #artistsObj.getFax()#
            #artistsObj.getemail()#

Getting Started with ColdFusion-ORM

Manjukiran — Mon, 13 Jul 2009 19:46:58 +0000

ColdFusion-ORM is the one of the top features in ColdFusion 9. This feature is close to my heart as I have worked on it the whole release right from its inception – specification, design, development and testing – most of the time involved in testing it. Believe it or not, I have written more than 500 test cases for ORM which include 2000+ CFM/CFC files. I am making an effort to help the community to get started on this feature by posting a series of examples that would introduce you to ColdFusion-ORM. The documentation does cover the ColdFusion-ORM stuff in good detail. But I believe in the “Learn as you code” approach. I will post a series of examples – each example would introduce a new concept in ColdFusion-ORM. I hope you would like this approach. and as you read the posts, do provide me with timely feedback so that I can mend my further examples as appropriate.

Task:
Basic ColdFusion-ORM Example

Stuff that you would learn:
To Configure ORM for a ColdFusion application.
Configuring a datasource to be used by ORM.
Mapping a table to a CFC.
Using the EntityLoad method and iterating over the resultset.
To Log the SQLs generated by ORM to the ColdFusion console.

Steps to Run the example:
- This example needs the cfartgallery. This is shipped with ColdFusion by default.
- Create a directory say “basicorm” under webroot.
- Create the following files – Application.cfc, Artists.cfc and index.cfm.
- Run the URL http://localhost:8500/basicorm/index.cfm

I have interspersed the example with a lot of comments. You can understand the concept by just following the comments starting with Application.cfc and then Artists.cfc and then index.cfm.

Application.cfc

/*
You always need a Application.cfc to work with ORM.  You
need to set ormenabled to true for the application to use ORM.
Note that ORM Configuration and mapping is generated and loaded
when the aplication starts.
*/
component
{
    //Name of the application
    this.name = "ORM_BasicExample";

    //ormenabled should be set to true so that ORM is enabled for this application
    this.ormenabled = "true";

    //Set the datasource that needs to be used by the ORM Functions.  You can also set this in the ormsettings struct
    this.datasource = "cfartgallery";

    //Set logSQL to true.  This will log SQLs to the console.
    this.ormsettings.logSQL = "true";
}

Artists.cfc

/*
FileName: Artists.cfc
Usually one CFC maps to one table. In this case, the CFC Artists.cfc maps to the table Artists. 

Persistent attribute should be set to true for cfcomponent so that ColdFusion knows
that mapping needs to generated for this CFC. 

If the name of the component is not the same as that of the table, specify the table
name. 

EntityName should be specified for the CFC which will be used by the Entity* functions
to do CRUD operations on this CFC. If EntityName is not specified, then, the name of
the component is taken as the entityname.
*/ 

component persistent="true" entityname="Artists" table="Artists"
{ 

/*Usually one property corresponds to one column in the table. In this case, the property
"firstname" corresponds to the column FIRSTNAME in the Employees table.
*/
property name="firstname"; 

/*
fieldtype="id" denotes that the property "id" is the primary key of the table Art.
ColdFusion will figure it out by inspecting the database if not specified. 

column attribute is used to define the name of the field in the table to which this
property maps to. If the column attribute is not specified, then, the name of the
property is taken as the name of the field. 

Generator attribute is used to auto-generate the primarykey when a new record is added.
Here we use increment generator. To know more about generators, refer ColdFusion ORM documentation.
*/
property name="id" column="ARTISTID" generator="increment"; 

/*
Few other properties which map to the appropriate columns in the Employees table
*/
property name="lastname";
property name="address";
property name="city";
property name="state";
property name="postalcode";
property name="email";
property name="phone";
property name="fax";
property name="thepassword"; 

}

index.cfm




   /*
      Call ormreload() function so that ORM configuration/mapping is always created afresh
      when index.cfm is called.  This is convenirent to have in development time.  You shouldn't
      do this in production
   */
   ormreload();

    /*
     Load the Artist records to display them.  There are a number of
     variations to the EntityLoad method which will help you to retrieve
     the records the way you want. Refer the documentation for EntityLoad for details.
   */
   artists = EntityLoad("Artists");

    /*
     Display the Artist records that you just loaded
    */
    for (i=1;i" & artistObj.getFirstName() & " " & artistObj.getLastName() & "
");
        WriteOutput("Address: " & artistObj.getAddress() & " " & artistObj.getCity() & " " &
                    artistObj.getState() & " " & artistObj.getPostalCode() & "
");
        WriteOutput("Ph: " & artistObj.getPhone() & "
");
        WriteOutput("Fax: " & artistObj.getFax() & "
");
        WriteOutput("EMail: " & artistObj.getEmail() & "
");
        WriteOutput("
");
    }

ID	NAME	ADDRESS	PHONE	FAX	EMAIL
#artistsObj.getid()#	#artistsObj.getfirstname()# #artistsObj.getlastname()#	#artistsObj.getaddress()# #artistsObj.getCity()# #artistsObj.getState()# #artistsObj.getPostalCode()#	#artistsObj.getphone()#	#artistsObj.getFax()#	#artistsObj.getemail()#