Modifying an entity instance

Modifying an entity's data (the entity instance) can be done in multiple ways:

1. Loading an existing entity in memory, alter one or more fields (not sequenced fields) and call a DataAccessAdapter object's SaveEntity() method
2. Create a new entity, set the primary key values (used for filtering), set the IsNew property to false, set one or more other fields' values and call DataAccessAdapter.SaveEntity(). This will not alter the PK fields.
3. Via the DataAccessAdapter's UpdateEntitiesDirectly() method, specifying the primary key fields as the filter.

These different ways are described more in detail below.

Altering entity property values

DataAccessAdapter's SaveEntity() method will see that the entity passed to it is new or not, and will use an UPDATE query to alter the entity's data in the persistent storage and an INSERT query to insert a new instance into the persistent storage. An UPDATE query will only update the changed fields in an entity that is saved. If no fields are changed, no update is performed.

If you've loaded an entity from the database into memory and you've changed one or more of its primary key fields, these fields will be updated in the database as well (except sequenced columns). Changing PK fields is not recommended and changed PK fields are not propagated to related entities fetched in memory.

An example for code using this method:

CustomerEntity customer = new CustomerEntity("CHOPS");
using(DataAccessAdapter adapter = new DataAccessAdapter())
{
    adapter.FetchEntity(customer);
    customer.Phone = "(605)555-4321";
    adapter.SaveEntity(customer);
}

Dim customer As New CustomerEntity("CHOPS")
Using adapter As New DataAccessAdapter())
    adapter.FetchEntity(customer)
    customer.Phone = "(605)555-4321"
    adapter.SaveEntity(customer)
End Using

This will first load the Customer entity CHOPS into memory, alter one field, Phone, and then save the entity instance back into the persistent storage. Because the loading of CHOPS already set the primary key, we can just alter a field and call SaveEntity(). The Update query will solely set the table field related to the entity field Phone to the new value.

Update an entity directly in the database

Reading an entity into memory first can be somewhat inefficient, if all we need to do is an update of an entity row in the database. The following procedure is more efficient in that it results in just an UPDATE query, without first reading the entity data from the database. The following code performs the same update as the previous example code illustrating option 1.

Because it doesn't need to read an entity first, we won't pass true to keep the connection open. Even though the PK field is changed, it is not updated, because it is not previously fetched from the database.

CustomerEntity customer = new CustomerEntity();
customer.CustomerID="CHOPS";
customer.Phone = "(605)555-4321";
customer.IsNew=false;
using(DataAccessAdapter adapter = new DataAccessAdapter())
{
    adapter.SaveEntity(customer);
}

Dim customer As New CustomerEntity()
customer.CustomerID = "CHOPS"
customer.Phone = "(605)555-4321"
customer.IsNew = False
Using adapter As New DataAccessAdapter()
    adapter.SaveEntity(customer)
End Using

We have to set the primary key field, so the Update method will only update a single entity, the CHOPS entity. First we specify the altering of a field, in this case Phone. Next, we have to mark the new, empty entity class instance as not being new, so SaveEntity() will use an UPDATE query, instead of an INSERT query.

This is done by setting the entity object's property IsNew to false. We'll set IsNew to false right before saving the entity. The reason to do this as the last action is to make it possible to set a field to null / Nothing using this system: setting a field to null / Nothing is a 'change of value' for new entities but for existing entities, if a field is already null / Nothing (which is the case with a new entity object) it isn't (null / Nothing changed into null / Nothing), and the field isn't seen as 'changed' and isn't updated.

As the last action we call SaveEntity(). This will not load the entity back in memory. If you want that, specify 'true' with the SaveEntity() call. Doing updates this way can be very efficient and you can use very complex update constructs e.g. when you apply an Expression to the field(s) to update. See for more information about Expression objects for fields Field expressions and aggregates.

Using UpdateEntitiesDirectly()

The DataAccessAdapter class allows you to manipulate an entity or group of entities directly in the database without first fetching them into memory. Below we're setting all Discontinued fields of all Product entities to false if the CategoryId of the product is equal to 3. UpdateEntitiesDirectly() (as well as its method for deletes DeleteEntitiesDirectly which deletes entities directly from the persistent storage) returns the number of entities affected by the call.

RelationPredicateBucket bucket = new RelationPredicateBucket(ProductFields.CategoryId == 3);
ProductEntity updateValuesProduct = new ProductEntity();
updateValuesProduct.Discontinued=true;
using(DataAccessAdapter adapter = new DataAccessAdapter())
{
    int amountUpdated = adapter.UpdateEntitiesDirectly(updateValuesProduct, bucket);
}

Dim bucket As New RelationPredicateBucket(ProductFields.CategoryId = 3)
Dim updateValuesProduct As New ProductEntity()
updateValuesProduct.Discontinued = True
Using adapter As New DataAccessAdapter()
    Dim amountUpdated As Integer = adapter.UpdateEntitiesDirectly(updateValuesProduct, bucket)
End Using