User Guide Cancel

Work with objects

Object-Relational Mapping (ORM) allows you to work with objects and have them saved to the database automatically.

Object-Relational Mapping (ORM) allows you to work with objects and have them saved to the database automatically. It can greatly simplify create-read-update-delete (CRUD) operations and make your code more object-oriented. Under the hood, ColdFusion uses the ORM framework called Hibernate.

Operations can be performed on an Entity object, and the auto-generated methods in the entity can be called.

For more information on objects in ORM, read the following:

Setting up your application

Define the application in Application.cfc. To use ColdFusion ORM, you need to specify the following settings in Application.cfc:

component{
this.name="Test_ORM_Example";
this.ormEnabled="true";
this.dataSource="cfdocexamples";
}
component{ this.name="Test_ORM_Example"; this.ormEnabled="true"; this.dataSource="cfdocexamples"; }
component{
 this.name="Test_ORM_Example";
 this.ormEnabled="true";
 this.dataSource="cfdocexamples";
}

Line 2 specifies the identifier, line 3 tells ColdFusion to use the ORM, and line 4 specifies which datasource to be used.

Mapping an object to the database

You define ColdFusion objects in ColdFusion Components (CFCs). To map a ColdFusion object to a database table using the ORM, you must create a CFC for that object.

Give your CFC the same name as the table. For example, for the table called EMPLOYEE, create a CFC called Employee.cfc and add the following code:

component persistent="true" {
property name="employeeId" column="emp_id" fieldtype="id" type="numeric" generator="increment";
}
component persistent="true" { property name="employeeId" column="emp_id" fieldtype="id" type="numeric" generator="increment"; }
component persistent="true" {
  property name="employeeId" column="emp_id" fieldtype="id" type="numeric" generator="increment";
 }

When persistent=”true”, ORM manages the data for the object.

Create a file file1.cfm and add the following code:

<cfscript>
ORMReload();
employees = EntityLoad('Employee);
writedump(employees);
</cfscript>
<cfscript> ORMReload(); employees = EntityLoad('Employee); writedump(employees); </cfscript>
<cfscript>
 ORMReload();
 employees = EntityLoad('Employee);
 writedump(employees);
</cfscript>

When you access your application for the first time, the results take longer to load. The ORM does not get reloaded on every request. When you change the ORM configuration in Application.cfc or in a persistent CFC, the ORM must reload to capture the changes. Use the ORMReload function to reload the ORM.

Run the file file1.cfm and you see the following result:

The persistent attribute in Employee.cfc tells ColdFusion that this CFC maps to a database table, Employee.

Add property statements to the CFC, as shown below:

component persistent="true" {
property name="employeeId" column="emp_id" fieldtype="id" type="numeric" generator="increment";
property name="firstName";
property name="lastName";
property name="salary";
property name="contract";
}
component persistent="true" { property name="employeeId" column="emp_id" fieldtype="id" type="numeric" generator="increment"; property name="firstName"; property name="lastName"; property name="salary"; property name="contract"; }
component persistent="true" {
  property name="employeeId" column="emp_id" fieldtype="id" type="numeric" generator="increment";
  property name="firstName";
  property name="lastName";
  property name="salary";
  property name="contract";
}

In the code sample above, the primary key is specified as the fieldtype attribute to have a value of "id". In addition, the column has a numeric datatype and that the generator attribute has a value of increment, which tells the ORM that it should automatically generate a primary key for new records.

Displaying data

In the data you have displayed, each property has some associated methods. One set of methods is prefixed with Get, and the other set is prefixed with Set.

The following code sample uses the Get property to retrieve the first names of all employees.

<cfscript>
ORMReload();
employees = EntityLoad('Employee');
n=arraylen(employees);
for (i=1;i<=n;i++){
writeoutput(employees[i].getFirstName() & "<br>");
}
</cfscript>
<cfscript> ORMReload(); employees = EntityLoad('Employee'); n=arraylen(employees); for (i=1;i<=n;i++){ writeoutput(employees[i].getFirstName() & "<br>"); } </cfscript>
<cfscript>
 ORMReload();
 employees = EntityLoad('Employee');
 n=arraylen(employees);
 for (i=1;i<=n;i++){
  writeoutput(employees[i].getFirstName() & "<br>");
 }
</cfscript>

The output is as follows:

Inserting a record

Use the functions EntityNew and EntitySave to insert records into the database. For example,

<cfscript>
employee = EntityNew("Employee");
employee.setFirstName("Tom");
employee.setLastName("Jones");
employee.setSalary(100000);
employee.setContract("Y");
EntitySave(employee);
</cfscript>
<cfscript> employee = EntityNew("Employee"); employee.setFirstName("Tom"); employee.setLastName("Jones"); employee.setSalary(100000); employee.setContract("Y"); EntitySave(employee); </cfscript>
<cfscript>
 employee = EntityNew("Employee");
 employee.setFirstName("Tom");
 employee.setLastName("Jones");
 employee.setSalary(100000);
 employee.setContract("Y");
 EntitySave(employee);
</cfscript>

When you view all the records in the database, the new record appears, as shown below:

Updating a record

To update an existing object, get the ColdFusion object that represents the record in the database. Use the function EntityLoadByPK to specify the primary key of a record and then return the object with that record's data. For example,

<cfscript>
employee = EntityLoadByPK("Employee",1958);
// change the salary
employee.setSalary(125000);
</cfscript>
<cfscript> employee = EntityLoadByPK("Employee",1958); // change the salary employee.setSalary(125000); </cfscript>
<cfscript>
 employee = EntityLoadByPK("Employee",1958);
 // change the salary
 employee.setSalary(125000);
</cfscript>

The output of the update is as follows:

In the above output, the area in blue shows that the salary has been updated for employee with Primary Key 1958.

Deleting a record

Use the function EntityDelete with EntityLoadByPK function to delete a record. For example,

<cfscript>
// load an entity by id
employee = EntityLoadByPK("Employee", 1958);
// delete the entity
EntityDelete(employee);
</cfscript>
<cfscript> // load an entity by id employee = EntityLoadByPK("Employee", 1958); // delete the entity EntityDelete(employee); </cfscript>
<cfscript>
 // load an entity by id
 employee = EntityLoadByPK("Employee", 1958);
 // delete the entity
 EntityDelete(employee);
</cfscript>

When you list all the records in the Employee database, you can see that the employee with Primary Key 1958 is now removed.

Get help faster and easier

New user?