Entity Object Management

• Jan 28, 2021
• 5 minutes to read

An entity object (an instance of an entity class defined in an entity model) represents a fact about its entity. In terms of relational databases, an entity object corresponds to a record in one or more (joined) tables and contains values for one or more columns. Managing entity objects and storing/updating their data via a session component that is connected to a database allows you to perform corresponding operations with its table records.

Entity Object Lifetime

You can create, modify, and destroy entity objects in the same manner as you do with normal objects. However, no changes made to entity objects are reflected in a data store until you connected it to a session component and associated this component with the entity objects. To associate them, do one of the following via a session component:

• Perform any CRUD operation (described below);

• Attach an entity object using the Attach procedure.

Important

Once associated with an entity object, the session component is responsible for destroying it, deallocating memory, and finalizing all object-related operations.

CRUD Operations

The acronym stands for Create, Read, Update, and Delete operations, which you can perform with entity objects via a session component and reflect them in a data store connected to this component. The operations and examples on how to perform them are listed below.

Creating Records

You can create an entity object (an instance of an entity class) by doing one of the following:

• Call the entity class’s constructor;

• Call a session component’s CreateObject function and pass the entity class’s type as a parameter.

Then, call a session component’s Save method and pass the created entity object as a parameter to create a corresponding record and initialize it with the object’s property/field values.

The following code creates a record in a table to which the TPerson entity class described in the Entity Model Design and Customization topic maps its data.

uses
  ..., dxEMF.Core, dxEMF.Attributes, dxEMF.Types;
var
  APerson: TPerson;
  // ...
begin
  // ...
  // Creating a database and updating its schema to match 
  // the TPerson entity class declaration (this creates the Person table)
  dxEMFSession.DataProvider.Options.AutoCreate := TdxAutoCreateOption.DatabaseAndSchema;
  dxEMFSession.CreateSchema(TPerson);
  // Creating an entity object and specifying its properties
  APerson := TPerson.Create;
  APerson.Age := 25;
  APerson.Name := 'John Doe';
  // Saving the entity object, creating a corresponding record 
  // in the Person table and populating this record with the object's data
  dxEMFSession.Save(APerson);
end;

Reading Records

This operation retrieves data store records as entity objects using queries built with LINQ expressions, object-based criteria, or criteria strings. Query results are returned as object collections and LINQ expression results, which you can enumerate and access elements (entity objects) and their data. Refer to the Querying Data topic to learn more.

Updating Records

This operation includes:

• Reading data from data store records to entity objects (see the section above);

• Modifying properties and fields in these objects;

• Apply the changes to the data store using a session component’s Save method.

The following code example modifies the Age and Name property values of the TPerson entity object created in the previous section and updates the record.

APerson.Age := 28;
APerson.Name := 'John Smith';
// Saving the entity object and updating the corresponding record 
// with new values
dxEMFSession.Save(APerson);

Note that each call to the Save method accesses a data store and updates the corresponding record (and aggregated records), which may take time and significantly hinder the performance when updating multiple records. For batch updates, we recommend that you use the Track Changes mode (see below) to accumulate all the changes and apply them in a batch update, similar to a database transaction.

Deleting Records

You can delete an entity object using any of the following methods:

• Pass this entity object to a session component’s Delete method;

• Remove this entity object from an object collection whose DeleteObjectOnRemove property is set to True.

As with the Save method, we recommend that you delete multiple entity objects in Track Changes mode to improve performance.

Track Changes Mode

The Track Changes mode works in a similar way to a database transaction, which groups atomic operations and either applies or discards all of them, based on a condition. In this mode, a session component tracks all entity object changes to a data store and accumulates them in memory until either of the following takes place:

• The session component’s FlushChanges method is called to apply the changes to the data store;

• The session component’s DropChanges method is called to discard pending changes to the data store. This, however, retains changes in entity objects.

To enable the mode and start tracking object changes, call the session component’s BeginTrackingChanges method.

The following code example handles CRUD operations in Track Changes mode.

dxEMFSession.BeginTrackingChanges;
try
  <Your CRUD operations here>
  // ...
  // Applying the changes
  dxEMFSession.FlushChanges;
except
  // Discarding the changes
  dxEMFSession.DropChanges;
  <Handle an error here (log it, display a message, etc.)>
end;