Lab - Introduction to Cold Fusion ORM

INTRODUCTION TO COLDFUSION ORMADOBE MAX 2010

Adam Lehman ([email protected]

Introduction to ColdFusion ORM Page 1 of 21

SETUP & CONFIGURATION

Before you proceed, please note the following: Throughout the document, the following styles are used to simplify instructions. Menu items and field prompts are formatted in bold text. Text you need to enter or type is always in a monotype font.

This hands-on lab requires the following software installed:

Adobe ColdFusion 9 Adobe ColdFusion Builder Lab Demo Assets

o Sample cfartgallery databaseo Example ColdFusion templates (optional)

LAB 1: MAPPING A CFC TO A DATABASE

This lab demonstrates the simplest form of persisting data in ColdFusion using object-relational mapping. You will walk through the steps required to configure an ORM-enabled ColdFusion application. Then you will create a ColdFusion component (CFC) that corresponds to an existing database table. Finally, you will query the database through the use of the entityLoad() function. For this lab you will be working in the lab1 directory.

EXERCISE 1: CREATE NEW PROJECT – DEFINE ORM SETTINGS

1. If you have not yet opened ColdFusion Builder, please do so now.2. Close any open project in ColdFusion Builder.3. Open the File menu and select New ColdFusion Project

4. Define the Project Information:

a. Specify the Project Name as: ORM Lab.

b. Uncheck Use Default Location.c. Specify the Project Location as: C:\ColdFusion9\wwwroot\ORMLab\d. Click the Next button.

5. Defined the Server Details:a. Select ColdFusion 9 from the server drop-down.b. Click the Finish button.

6. Create a new component named Application.cfc in the lab1 directory to define the ORM settings:a. Open the File menu and select New ColdFusion Componentb. Specify the Component Name as: Applicationc. Click the Finish button.

7. Configure the ORM settings by adding the following code to Application.cfc:

<cfcomponent> <cfset this.name = "ORMLab" /> <cfset this.ormenabled = "true" /> <cfset this.datasource = "cfartgallery" /></cfcomponent>


Additional ORM setting can be defined in the form of a structure using the this.ormsettings variable.

EXERCISE 2: CREATE A PERSISTENT CFC

1. Create a new component named Artist.cfc in the lab1 directory.a. Open the File menu and select New ColdFusion Componentb. Specify the Component Name as: Artistc. Click the Finish button.

2. Define the properties of the Artist entity by adding the following code to Artist.cfc:

<cfcomponent persistent="true" table="Artists" entityname="Artist"> <cfproperty name="ArtistID" fieldtype="id" /> <cfproperty name="FirstName" /> <cfproperty name="LastName" /> <cfproperty name="Email" /> <cfproperty name="Address" /> <cfproperty name="City" /> <cfproperty name="State" /> <cfproperty name="PostalCode" /></cfcomponent>

EXERCISE 3: QUERY THE DATABASE FOR ALL RECORDS

1. Create a new template named index.cfm in the lab1 directory.a. Open the File menu and select New ColdFusion Pageb. Specify the Name as: indexc. Click the Finish button.

2. Query all artist records from the database by adding the following code to index.cfm:

<cfset data = entityLoad('Artist') /><cfdump var="#data#" />

3. Select the Firefox tab on the bottom left of the code editor to run the template.

If you have completed all of the above steps correctly, you should see a cfdump depicting an array of Artist entities. One entity is created for each record returned from the Artists table.

When used with only one parameter, the entityLoad() function is equivalent to a select statement without a where clause in SQL.

EXERCISE 4: QUERY THE DATABASE FOR MATCHING RECORDS

1. Return only entities that match the specified property by updating the following code in index.cfm:


<cfset data = entityLoad('Artist', {LastName='Buntel'}) /><cfdump var="#data#" />


You should now see a cfdump depicting an array with only two Artist entities for Ellery and Emma Buntel.

Try experimenting with different entity properties. The second parameter of entityLoad() is an inline structure. You can use multiple key/value pairs seperated by a comma. Try the following combination:{State='CO', City='Denver'}

LAB 2: WORKING WITH ORM DATA


This lab will walk you through the various ways of working with ORM data. First you will loop through an array of entities to create a table of results. Finally, you will convert an array of entity CFCs to a traditional ColdFusion query using the entityToQuery() function. For this lab you will be working in the lab2 directory which should already include the Application.cfc and Artist.cfc from the previous lab.

EXERCISE 1: USING DYNAMIC METHODS TO ACCESS PROPERTIES


2. Query all artist records from the database and display a list of artists by adding the following code to index.cfm:

<cfset data = entityLoad('Artist') />

<cfoutput><ul>

<cfloop from="1" to="#arrayLen(data)#" index="i"><cfset artist = data[i] /> <li>#artist.getFirstName()# #artist.getLastName()#</li>

</cfloop></ul></cfoutput>


When working with entities, properties are accessed via method calls instead of being accessed directly (like with a ColdFusion query). However, you will notice that the Artist.cfc you created in the previous exercise did not


include any <cffunction> tags. Instead of defining these manually, ColdFusion will automatically create getters/setters based on the <cfproperty> tags.

EXERCISE 2: CREATING CUSTOM METHODS TO ACCESS PROPERTIES

1. Open Artist.cfc from the lab2 directory.

2. Create a new method titled getFullName() by adding the following code to Artist.cfc:

<cfcomponent persistent="true" table="Artists" entityname="Artist"><cfproperty name="ArtistID" fieldtype="id" /><cfproperty name="FirstName" /><cfproperty name="LastName" /><cfproperty name="Email" /><cfproperty name="Address" /><cfproperty name="City" /><cfproperty name="State" /><cfproperty name="PostalCode" />

 <cffunction name="getFullName" returntype="string">

<cfset var fullname = getFirstName() & ' ' & getLastName() /><cfreturn fullname />

</cffunction>

</cfcomponent>

3. If it is not already open, open index.cfm from the lab2 directory.4. Replace the two method calls to getFirstName() and getLastName() with the new

getFullName() method by adding the following code to index.cfm:


<cfoutput><ul>

<cfloop from="1" to="#arrayLen(data)#" index="i"><cfset artist = data[i] /> <li>#artist.getFullName()#</li>

</cfloop></ul></cfoutput>


EXERCISE 3: WORKING WITH ENTITIES AS A QUERY

1. If it is not already open, open index.cfm from the lab2 directory.2. Convert the entity array to a ColdFusion query using the entityToQuery() function by updating the

following code in index.cfm:



<cfset artists = entityToQuery(data) />

<ul><cfoutput query="artists">

<li>#FirstName# #LastName# <br />(#City#, #State#)

</li></cfoutput></ul>


The custom method getFullName() created in the previous exercise is not converted to a ColdFusion query by the entityToQuery() function. Only properties defined with <cfproperty> are converted.

LAB 3 – SAVING DATA WITH ORM

This lab will cover the various ways of saving data with ORM. First you will update existing records by using the dynamic setter methods of an entity. Then you will create a brand new entity and persist it to the database using the entitySave() function. For this lab you will be working in the lab3 directory which should already include the Application.cfc and Artist.cfc from the previous labs.

EXERCISE 1: UPDATING RECORDS


2. Query a single record from the database and explore its properties by adding the following code to index.cfm:

<cfset artist = entityLoad('Artist', 1, true) />

<cfdump var="#artist#" />



You should now see a cfdump depicting an array with one Artist entity.

You may have noticed that the entityLoad() function is a special function. In the example above you used the entityLoad() function to return a record based on a number. However, in the previous lab you specified a structure. Because the entityLoad() function can take different parameter types, it is considered an overloaded function.

When you specify the 3rd argument of the entityLoad() function as true, ColdFusion will only return a single entity instead of an array of entities. You should only use the argument when you are certain that only one entity should be returned.

4. Update the properties of the entity and display the result by adding the following code to index.cfm:


<cfset artist = entityLoad('Artist', 1, true) />

<cfset artist.setFirstName('Adam') /><cfset artist.setLastName('Lehman') /><cfset artist.setEmail('[email protected]') /><cfset artist.setAddress('123 Main Street') /><cfset artist.setCity('RockVegas') /><cfset artist.setState('MD') /><cfset artist.setPostalCode('20852') />

<cfset entitySave(artist) />

<cfdump var="#artist#" />

5. Select the Firefox tab on the bottom left of the code editor to run the template. You should now see a cfdump depicting an entity with the updated properties.

6. Open the RDS Dataviewa. Open the Window menu and select Show View RDS Dataview

7. Expand the ColdFusion 9 tree to view the tables in the cfartgallery datasource by clicking ColdFusion 9 cfartgallery Tables

8. Display the contents of the Artists table by right-clicking the APP.ARTISTS table and selecting Show Table Contents


The entitySave() function commits the entity back to the database whether the record previously existed in the database or not. Under the hood, ColdFusion is automatically generating the SQL UPDATE or INSERT statements.

EXERCISE 2: CREATING NEW RECORDS


2. Specify the generator for ArtistID by adding the following code to the <cfproperty> tag in Artist.cfc:

<cfcomponent persistent="true" table="Artists" entityname="Artist"><cfproperty name="ArtistID" fieldtype="id" generator="identity" /><cfproperty name="FirstName" /><cfproperty name="LastName" /><cfproperty name="Email" /><cfproperty name="Address" /><cfproperty name="City" /><cfproperty name="State" /><cfproperty name="PostalCode" />



</cffunction>

</cfcomponent>

3. If it is not already open, open index.cfm from the lab3 directory.4. Create a new entity and save it to the database by updating the following code in index.cfm:


<cfset artist = entityNew('Artist') />

<cfset artist.setFirstName('Terry') /><cfset artist.setLastName('Ryan') /><cfset artist.setEmail('[email protected]') /><cfset artist.setAddress('123 Main Street') /><cfset artist.setCity('Philadelphia') /><cfset artist.setState('PA') /><cfset artist.setPostalCode('19107') />


<cfdump var="#artist#" />


5. Select the Firefox tab on the bottom left of the code editor to run the template. If you followed the above steps correctly, you should see the following error message:

The cause for the error above is due to the fact that ColdFusion had already loaded the Artist entity into memory. After you updated the generator attribute, you need to instruct ColdFusion to refresh the ORM session and settings with the ormReload() function. The ormReload() function is an handy function for use while developing, but shouldn’t be used in your completed application (much like the <cfdump> tag).

6. To fix the above error, reload the ORM session and settings by adding the following line of code to index.cfm:

<cfset ormReload() />

<cfset artist = entityNew('Artist') />

<cfset artist.setFirstName('Terry') /><cfset artist.setLastName('Ryan') /><cfset artist.setEmail('[email protected]') /><cfset artist.setAddress('123 Main Street') /><cfset artist.setCity('Philadelphia') /><cfset artist.setState('PA') /><cfset artist.setPostalCode('19107') />




<cfdump var="#artist#" />


7. Open the RDS Dataviewa. Open the Window menu and select Show View RDS Dataview

8. Expand the ColdFusion 9 tree so view the tables in the cfartgallery datasource by clicking ColdFusion 9 cfartgallery Tables

9. Display the contents of the Artists table by right-clicking the APP.ARTISTS table and selecting Show Table Contents

By default, at the end of each request ColdFusion persists your changes to the database. If you would like to persist your changes manually you can use the ormFlush() function.

LAB 4 – WORKING WITH COMPLEX RELATIONSHIPS

This lab will walk you through the steps to define complex relationships. You will define a relationship between the Artist and a new Art entity. For this lab you will be working in the lab4 directory which should already include the Application.cfc and Artist.cfc from the previous labs.

EXERCISE 1: DEFINE A ONE-TO-MANY RELATIONSHIP

1. Create a new component named Art.cfc in the lab4 directory.a. Open the File menu and select New ColdFusion Componentb. Specify the Name as: Artc. Click the Finish button.

2. Define the properties of the Art entity by adding the following code to Art.cfc:

<cfcomponent persistent="true" table="Art" entityname="Art"><cfproperty name="ArtID" fieldtype="id" /><cfproperty name="Name" column="ArtName" /><cfproperty name="isSold" /><cfproperty name="description" /><cfproperty name="price" />

</cfcomponent>



4. Define the relationship between the artist and art entity by adding the following <cfproperty> tag to Artist.cfc:

<cfcomponent persistent="true" table="Artists" entityname="Artist"><cfproperty name="ArtistID" fieldtype="id" generator="identity" /><cfproperty name="FirstName" /><cfproperty name="LastName" /><cfproperty name="Email" /><cfproperty name="Address" /><cfproperty name="City" /><cfproperty name="State" /><cfproperty name="PostalCode" /><cfproperty name="Art" fieldtype="one-to-many" cfc="Art"

fkcolumn="ArtistID" />



</cffunction>

</cfcomponent>


6. Query a single record from the database and explore its properties by adding the following code to index.cfm:

<cfset artist = entityLoad('Artist', 1, true) />

<cfdump var="#artist#" />

7. Select the Firefox tab on the bottom left of the code editor to run the template. You should see a cfdump depicting an Artist entity with an array of Art entities.


EXERCISE 2: DEFINE A MANY-TO-ONE RELATIONSHIP

1. If it is not already open, open index.cfm from the lab4 directory.2. Query the art entities to explore their properties by updating the following code in index.cfm:

<cfset art = entityLoad('Art') />

<cfdump var="#art#" />

3. Select the Firefox tab on the bottom left of the code editor to run the template. You should now see a cfdump depicting an array of Art entities without an embedded Artist entity. The relationship you defined in the Artist entity is not present when you query Art directly.


4. Open Art.cfc from the lab4 directory.

5. Define the relationship between the Art and Artist entity by adding the following <cfproperty> tag to Art.cfc:

<cfcomponent persistent="true" table="Art" entityname="Art"><cfproperty name="ArtID" fieldtype="id" /><cfproperty name="Name" column="ArtName" /><cfproperty name="isSold" /><cfproperty name="description" /><cfproperty name="price" /><cfproperty name="Artist" fieldtype="many-to-one" cfc="Artist"

fkcolumn="ArtistID" /></cfcomponent>


6. If it is not already open, open index.cfm from the lab4 directory.7. Query a single Art entity and access the new Artist property by updating the following code in

index.cfm:

<cfset ormReload() />

<cfset art = entityLoad('Art', 1, true) />

<cfset artist = art.getArtist() />

<cfdump var="#artist#" />

8. Select the Firefox tab on the bottom left of the code editor to run the template. You should now see a cfdump depicting the Art entity with an embedded Artist entity.


LAB 5 – ADVANCED ORM QUERIES

This lab will explore some of the more advanced ways to query data using ORM. The first exercise will show you how to query data using an example entity. The second exercise will introduce you to the Hibernate Query Language (HQL). For this lab you will be working in the lab5 directory which should already include the Application.cfc, Artist.cfc and Art.cfc from the previous labs.

EXERCISE 1: QUERY BY EXAMPLE


2. Query all artist records from the database that match the specified properties using the entityLoadByExample() function by adding the following code to index.cfm:

<cfset artist = new Artist() />

<cfset artist.setLastName('Buntel') />

<cfset data = entityLoadByExample(artist) />

<cfdump var="#data#" />

3. Select the Firefox tab on the bottom left of the code editor to run the template. You should now see a cfdump depicting an array of Artist entities with the LastName matching Buntel.


EXERCISE 2: QUERY WITH HQL (SIMPLE)

1. If it is not already open, open index.cfm from the lab5 directory.2. Query all the Artist records by adding the following code to index.cfm:

<cfset data = ormExecuteQuery("from Artist") />



3. Select the Firefox tab on the bottom left of the code editor to run the template. You should see a cfdump depicting an array of Artist entities. ormExecuteQuery(“from Artist”) is equivalent to entityLoad(“Artist”).

The statement from Artist might look like common SQL, but it’s technically Hibernate Query Language (HQL). HQL has many similarities to SQL, but it’s entity/property based instead of table/column based. It’s important to note that HQL is case sensitive.

EXERCISE 3: QUERY WITH HQL (ADVANCED)

1. If it is not already open, open index.cfm from the lab5 directory.2. Query all the Artist records by adding the following code to index.cfm:

<cfset data = ormExecuteQuery("from Artist where email LIKE '%adobe.com'") />


Select the Firefox tab on the bottom left of the code editor to run the template. You should see a cfdump depicting an array of Artists with email addresses that end in adobe.com.


Here are a few other advanced HQL queries you can try.

Example using unnamed parameters:

<cfset params = ["New York", "NY"] />

<cfset data = ormExecuteQuery("from Artist where City = ? and State = ?", params) />


Example using named parameters:

<cfset params = {state='CA'} />

<cfset data = ormExecuteQuery("from Artist where State = :state", params) />


Example using aggregate functions:

<cfset data = ormExecuteQuery("select count(ArtistID) from Artist") />

Documents

Lab - Introduction to Cold Fusion ORM