Establishing Business Object Relationships

Establishing parent/child relationships between business objects provides two key features:

It allows messages to be cascaded down the parent/child hierarchy
It allows multiple business objects to participate in a single database transaction

Establishing the Relationship

To establish a parent/child relationship, you simply instantiate the parent and child business objects, then pass a child business object reference to the parent object's RegisterChildBizObj method.

For example, in C#:

// Create a Customer object
Customer customer = new Customer();
// Create an Order object
Order order = new Order();
 
// Register the Order object as a child of the Customer object
customer.RegisterChildBizObj(order);

And in VB .NET:

'' Create a Customer object
Dim Customer = New Customer()
'' Create an Order object
Dim Order = New Order()
 
'' Register the Order object as a child of the Customer object
Customer.RegisterChildBizObj(Order)

A business object can have an unlimited number of child business objects. In addition, a child business object can have its own children (which would be grandchildren of the parent object). You can extend the hierarchy for an unlimited number of generations (parent -->, child -->, grandchild -->, great-grandhchild, and so on).

Cascading Messages Down the Hierarchy

When you call the following methods on a business object, you can specify that the corresponding method is automatically called on the child business object:

CancelEntity
CancelEntityList
DeleteEntity
DeleteEntityList
NewEntity
NewEntityList
SaveEntity
SaveEntityList

If you want these methods to be automatically called in a child business object, you can set one or more of the following child business object properties to true (they're false by default):

AutoCancelOnParentCancel
AutoDeleteOnParentDeleted
AutoEmptyOnParentAdded
AutoNewOnParentAdded
AutoSaveOnParentSaved

Passing Broken Rules Up the Hierarchy

When you call a parent business object's SaveEntity() or SaveEntityList() method, it calls the child business object's corresponding Save method--IF you set the child business object's AutoSaveOnParentSaved property to True. Any broken rules encountered by the child automatically bubble up to the parent. This means you only have to check the parent object to get a list of broken rules encountered by either the parent or child. This feature works for any number of child objects and any number of parent/child levels.

Getting Parent Object Primary Key Values

One of the most important pieces of information a child business object needs is the current primary key value(s) of the parent business object. When a child object handles an event raised by a parent business object this information is automatically passed in the event arguments. If you want to access this key information outside of an event handler, it can be retrieved from the child business object's ParentKeyValue and ParentKeyValues properties. These properties contain the parent business object's primary key value(s) the last time a parent event was handled.

Automatically Setting Parent Key Fields in Child Business Objects

When you establish a parent/child relationship between business objects and have specified to AutoSaveOnParentSaved, you can have MM .NET automatically populate the child business object's parent key field with the parent's current primary key value. To do this, simply set the child business object's ForeignParentKeyField property to the name of the key field in the child object's default table that contains a pointer to the parent's primary key field.

Participating in Transactions

When you establish a relationship between business objects, all objects participate in a single transaction. For details, see the topcis listed below.