Saving Business Entities

MM.NET business objects have a set of SaveEntity() and SaveEntityList() methods that allow you to save a single entity or a list of entities.

Using SaveEntity() and SaveEntityList() to Save Business Entities

The SaveEntity() method saves a single entity. The SaveEntityList() method saves one or more entities in a list. Both methods return one of the following mmSaveDataResult enumeration values:

• RulesBroken - Business rules were broken - data is NOT saved
  
• RulesPassed - All business rules passed, data is saved
  
• RuleWarnings - Warnings only, data is saved
  
• SaveCanceled - The Save was canceled
  
• Exception - An exception occurred when attempting to save
  

For details, see Understanding Business Rule Objects.

If you don't specify an entity when calling the SaveEntity() method the entity stored in the business object's Entity property is saved. If you don't specify a list of entities when calling SaveEntityList(), the list of entity objects stored in the business object's EntityList property is saved.

Example 1
Here is an example of code that calls SaveEntity() to save a single entity.

In C#:

// Create a new entity
Employee employee = new Employee();
EmployeeEntity employeeEntity = employee.NewEntity();
employeeEntity.FirstName = "";
employeeEntity.LastName = "";
employeeEntity.BirthDate = new DateTime(1960, 10, 9);
 
// Save the new entity
var saveResult = employee.SaveEntity(employeeEntity);
 
// If rules are broken get all broken rules
if (saveResult == mmSaveDataResult.RulesBroken)
{
	var brokenRules = employee.Rules.GetAllBrokenRules();
}

In VB .NET:

'' Create a New entity
Dim Employee = New Employee()
Dim EmployeeEntity = Employee.NewEntity()
EmployeeEntity.FirstName = ""
EmployeeEntity.LastName = ""
EmployeeEntity.BirthDate = New DateTime(1960, 10, 9)
 
'' Save the New entity
Dim saveResult = Employee.SaveEntity(EmployeeEntity)
 
'' If rules are broken, get all broken rules
If saveResult = mmSaveDataResult.RulesBroken Then
	Dim brokenRules = Employee.Rules.GetAllBrokenRules()
End If

Example 2
Here is an example of code that calls SaveEntityList() to save a list of entities.

In C#:

// Get all employees
Employee employee = new Employee();
mmBindingList<EmployeeEntity> employeeList = employee.GetAllEntities();
 
// Clear out the Title
foreach (var employeeEntity in employeeList)
{
	employeeEntity.Title = "";
}
 
// Save all employees
var saveResult = employee.SaveEntityList(employeeList);
 
// If rules are broken get all broken rules
if (saveResult == mmSaveDataResult.RulesBroken)
{
	var brokenRules = employee.Rules.GetAllBrokenRules();
}

In VB .NET:

'' Get all employees
Dim employee = New Employee()
Dim employeeList = employee.GetAllEntities()
 
'' Clear out the Title
For Each employeeEntity In employeeList
	employeeEntity.Title = ""
Next
 
'' Save all employees
Dim saveResult = employee.SaveEntityList(employeeList)
 
'' If rules are broken, get all broken rules
If saveResult = mmSaveDataResult.RulesBroken Then
	Dim brokenRules = employee.Rules.GetAllBrokenRules()
End If

SaveEntity Sequence

The following UML sequence diagram shows how the business object, business rule, and data access objects participate in the process of saving data in the SaveEntity method:

Here are the main things that happen in the SaveEntity() method:

1. The business object raises a "PreSaving" state change event.

2. The business object calls its own CheckRules() method, which in turn calls the rule object's CheckRules() method, passing a reference to the current Entity. The rule object checks all business rules and returns an mmSaveDataResult enumeration value indicating if there were broken rules or warnings.

3. If there are no broken rules, the business object raises the "Saving" state change event, then calls the data access object's SaveEntity method, passing a reference to the entity.

4. The business object raises the "Saved" state change event.

5. The SaveEntity() method returns one of the mmSaveDataResult enumeration values.

See also:
Retrieving a List of Business Entities with GetEntityList()