|
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 entitiesCreates 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.
Syntax<entity> EntityNew("<entityName>")
Save entitiesSaves 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.
SyntaxEntitySave(entity, [forceinsert])
Parameter
|
Description
|
entity
|
The Entity that needs to be saved in the
database.
|
forceinsert
|
If true, then ColdFusion always tries to
insert the entity as a new record.
|
Example:<cfset artist = EntityNew("Artist")>
<cfset artist.setFirstName("Marcia")>
<cfset artist.setlastName("Em")>
<cfset EntitySave(artist)>
Update objectsThe 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.
SyntaxEntitySave(entity, [forceinsert])
ExampleThe following example changes
the first name of an artist with an Artist ID 1:
<cfset artist1 = EntityLoad("Artist", 1, true)>
<cfset artist1.setFirstName("Garcia")>
<cfset EntitySave(artist1)>
Read/Load objectsEntities are loaded using the EntityLoad methods.
All EntityLoad methods take the entity name as
input.
SyntaxEntityLoad (entityname)
EntityLoad (entityname, id [, unique])
EntityLoad (entityname, filtercriteria [,unique]
EntityLoad(entityname, filtercriteria, sortorder [, options])
EntityLoadByExample(sampleentity [, unique])
EntityReload(entity)
ExamplesEntityLoad (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=true and 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 sortorder are
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 timeout are
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 objectsThis 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.
SyntaxEntityDelete(entity)
ExampleFor example, to delete an Artist
with ArtistID 5:
<cfset artist = EntityLoad('artist', 5, true)>
<cfset EntityDelete(artist)>
Convert object to queryThis method converts the input entity object or the input
array of entity objects to a query object. All the objects in the
input array should be of the same type. Relationship properties
are not be included in the result query.
SyntaxEntitytoQuery (orm_object)
EntitytoQuery (orm_object_array)
Example<cfset artists = EntityLoad("Artist")>
<cfset artistQuery = EntityToQuery(artists)>
|