Creating a new entity instance

To create a new entity instance, you first have to instantiate an empty entity class instance. In our example we'll use the Customer entity and we'll create a new Customer instance.

CustomerEntity customer = new CustomerEntity();

To create the entity in the persistent storage, two things have to be done:

1 the entity's data (which is new) has to be stored in the new entity class instance 2 the entity data (the entity instance) has to be persisted / saved in the persistent storage. Let's add the customer Foo Inc. to the database:

customer.CustomerID = "FOO";
customer.Address = "1, Bar drive";
customer.City = "Silicon Valey";
customer.CompanyName = "Foo Inc.";
customer.ContactName = "John Coder";
customer.ContactTitle = "Owner";
customer.Country = "USA";
customer.Fax = "(604)555-1233";
customer.Phone_Number = "(604)555-1234";
customer.PostalCode = "90211";
// save it. We require an adapter for this
using(DataAccessAdapter adapter = new DataAccessAdapter())
{
    adapter.SaveEntity(customer, true);
}

customer.CustomerID = "FOO"
customer.Address = "1, Bar drive"
customer.City = "Silicon Valey"
customer.CompanyName = "Foo Inc."
customer.ContactName = "John Coder"
customer.ContactTitle = "Owner"
customer.Country = "USA"
customer.Fax = "(604)555-1233"
customer.Phone_Number = "(604)555-1234"
customer.PostalCode = "90211"
' save it. We require an adapter for this
Using adapter As New DataAccessAdapter()
    adapter.SaveEntity(customer, True)
End Using

CustomerEntity has another field, Region, which isn't given a value. Region can be NULL and will end up as NULL in the database as it has no value in the entity saved.

Refetch and Out of sync behavior.

The code above will save the data directly to the persistent storage (database). The SaveEntity overload used also accepts a boolean for refetch. This boolean, here the value true is specified, controls whether the data of the entity is refetched right after the save action. Adapter requires this so the entity class instance contains the latest data and is 'in-sync'.

If we would have passed false or used the overload SaveEntity(entity), the entity class instance customer would have been marked 'out of sync'. This means that the entity's data has to be refetched from the database prior to reading from one of the entities properties. If you do not require the saved entity for any further processing, you don't need to refetch it and you can save yourself a roundtrip by simply omitting the 'true' in the SaveEntity() call. You can also flag an entity automatically as 'fetched' again. See Entity state control for details.

Sequences / Identity value refetch

The code is aware of sequences / identity columns and will automatically set the value for an identity / sequence column after the entity is physically saved inside SaveEntity(). The new value for sequenced columns is available to you after SaveEntity(), even though you haven't specified that the entity has to be refetched.

This can be helpful if you want to refetch the entity later. Because the entity saved is new (customer.IsNew is true), SaveEntity() will use an INSERT query. After a successful save, the IsNew flag is set to false and the State property of the Fields object of the saved entity is set to EntityState.Fetched (if the entity is also refetched) or EntityState.OutOfSync.