Perform create, read, update, delete operations on ORM Objects

In any data-centric application, you can perform the following operations on the database:

• Insert (Create)
• Update
• Retrieve
• Delete
  Once the object relational model is defined in a ColdFusion application, you can perform CRUD operations on the objects directly using the methods provided by ColdFusion ORM. ColdFusion ORM, in turn, takes care of persisting the object in the database.

Create entities

EntityNew
Creates an object for persistent CFC with the given entity name. This is similar to CreateObject but it uses entityname whereas CreateObject takes CFC name. If there is no CFC defined in the application with the given entityname, an error will be thrown.
If the persistent CFC has an init method, then the function EntityNew calls the init method while creating the object.

Syntax

Save entities

EntitySave
Saves or Updates the data of the entity and all related entities to the database. 
ColdFusion automatically tries to find if a new record should be inserted or an existing record be updated for the given entity. If forceinsert=true, then ColdFusion always tries to insert the entity as a new record.
Calling this method may not run the insert/update SQL immediately. It is possible that various SQL statements are queued and then run as a batch for performance reasons. The SQL statements are run when the ORM session is flushed.

Syntax

Example:

Update objects

EntitySave
The method to update an object is the same as saving an object. Load the object that needs to be updated, make updates, and save the object.

Syntax

Example

The following example changes the first name of an artist with an Artist ID 1:

Read/Load objects

Entities are loaded using the EntityLoad methods. All EntityLoad methods take the entity name as input.
If the persistent CFC has an init method, the methods call the init method while creating objects.

Syntax

Examples

• {{EntityLoad (entityname)}}Loads and returns an array of entities of the specified entity name. For example, to retrieve all the objects of the "artist" CFC:

  <cfset artist = EntityLoad('ARTIST')>

• {{EntityLoad (entityname, id , unique)}}Loads and returns an entity whose Primary key's value is id. The entity is returned as an array by default. If unique is true, then the entity is returned.If the entity has a composite key, then the id has to be specified as key-value pairs (ColdFusion struct).Example 1: This example loads the Artist object with PK 100 and returns a single-element array containing the artist object.

  <cfset artistArr = EntityLoad('Artist', 100)>

  Example 2:This example loads the Artist object with PK 100 and returns the artist object.

  <cfset artistobj = EntityLoad('Artist', 100, true)>

  Example 3:This example loads the OrderDetail object which has the composite key OrderID=100 and ProductID=1 and returns the orderdetail object.

  <cfset orderDetail = EntityLoad('orderdetails', {OrderID=100, ProductID=1}, true)>

• EntityLoad (entityname, filtercriteria ,unique}}Loads and returns an array of entities of the given entity name that matches the {{filtercriteria. filtercriteria is a key-value pair (ColdFusion struct) of property names and its values. If there are more than one key-value pair in filtercriteria, then they always use the AND operator. If you are sure that only one record exists that matches this filtercriteria, unique=true can be specified so that a single entity is returned instead of an array. If unique=trueand multiple records are returned, then an exception occurs. For example, to retrieve details of all artists that have state CA:

  <cfset artistsFromCA = EntityLoad('Artist', {state="CA"})>

  To retrieve a unique object, specify{{ unique= "true"}}. If more than one object satisfies the condition, an exception occurs.This example loads the artist object whose firstName is "Austin" and lastname is "Weber".

  <cfset artist = EntityLoad('artist', {firstname="Austin", lastname="Weber"}, "true")>

   

• EntityLoad(entityname,filtercriteria,sortorder, options)}}Loads and returns an array of entities that satisfy the {{filtercriteria that is sorted as specified by the sortorder parameter.filtercriteria is a key-value pair (ColdFusion struct) of property names and its values. If there are more than one key-value pairs in filtercriteria, then they always use the AND operator.sortorder is a string, and should be specified in the following syntax:"propname1 asc, propname2 desc, ..."Some examples of sortorderare as follows:"firstname asc, lastname desc""firstname""country, age desc"Example: To retrieve artists whose state is CA, and sorted by City and FirstName:

  <cfset artistsFromCA = EntityLoad('artist', {state="CA"}, "city asc, firstName")>

  Certain configuration options can be input as name-value pairs as options argument. Several options can be specified to control the behavior of entity retrieval.

  • maxResults: Specifies the maximum number of objects to be retrieved.
  • offset: Specifies the start index of the resultset from where it has to start the retrieval.
  • cacheable: Whether the result of this query is to be cached in the secondary cache. Default is false.
  • cachename: Name of the cache in secondary cache.

  • timeout: Specifies the timeout value (in seconds) for the query.
    Maxresults and timeoutare used for pagination.*Example*To load first 5 artists whose state is "CA" that are sorted on the firstName.

    <cfset artists = EntityLoad("Artist",{state='CA"}, "FirstName", {maxResults=5})>

     

• EntityLoadByExample(sampleentity ,unique)}}Loads and returns an array of objects that match the {{sampleentity. The filter criteria is constructed by ANDing all the non-null properties of the sampleentity.For example, to retrieve an array of objects matching the specified values:

  <cfset artist= CreateObject("component", "artist")> <cfset artist.setState("CA")> <cfset artist.setCity("Berkeley")> <cfset artist=EntityLoadByExample(artist)>

  If you are sure that only one record exists that matches the specified filtercriteria, you can specify unique=true so that a single entity is returned instead of an array. If unique=true and multiple records are returned, then an exception occurs.

• {{EntityReload(entity)}}Reloads data for an entity that is already loaded in this session. This method refetches data from the database and repopulates the entity.

Delete objects

EntityDelete
This method deletes the record from the database for the specified entity. Depending on the cascade attribute specified in the mapping, it also deletes the associated objects.

Syntax

EntityDelete(entity)

Example

For example, to delete an Artist with ArtistID 5:

Convert object to query

EntitytoQuery}}This method converts the input entity object or the input array of entity objects to a query object. The name of the properties are used as the query column names. Use the optional parameter {{Entity_name to return the query of the given entity in the case of inheritance mapping. All the objects in the input array should be of the same type. Relationship properties are not be included in the result query.

Syntax

Example 1

Example 2

Merge entities

EntityMerge
To attach an entity to the current ORM session you can use the entitymerge function. It copies the state of the given object onto the persistent object with the same identifier and returns the persistent object. 
If there is no persistent instance currently associated with the session, it is loaded. The given instance is not associated with the session. You need to use the returned object from this session. For details, see EntityMerge in CFML Reference.