Plugging into Business Object Events

Business objects are the source of some very important events. You can easily hook into these events to receive automatic notification when something "interesting" is about to happen, or has already happened to the state of a business object.

The StateChange Event

Whenever a business object's state changes (records are added, deleted, retrieved and so on), the business object raises the StateChangeevent. In fact, the StateChange event is raised twice - once before the state change is about to occur, and a second time after it has already occurred.

If you have registered an event handler method with the business object's StateChange event, the event handler method receives two parameters - a reference to the business object that raised the event, and an instance of the mmBusinessStateEventArgs class shown in the left side of this diagram:

As you can see, the mmBusinessStateEventArgs class contains four main properties:

Entity - The business object's current entity
EntityList - The business object's current entity list
PrimaryKeyValue - The value of the primary key in the business object's current entity.
PrimaryKeyValues - The values of primary keys in the business object's current entity. Used when the primary key is comprised of multiple properties.
State - The type of state change that is about to occur or has occurred.
TableName - (Classic ADO.NET only) The name of the associated table for which the event occurred

As you can see in the diagram, the State property is of the type mmBusinessState . The mmBusinessState enumeration lists all the possible values of the State property. Here is a description of when each of these events is raised.

Adding - Raised before adding a new entity.
Added - Raised after adding a new entity.
Canceling - Raised before canceling changes to an entity or entity list
Canceled - Raised after canceling changes to an entity or entity list.
Deleting - Raised before deleting an entity.
Deleted - Raised after deleting an entity.
Navigating - (Classic ADO.NET only) Raised before navigating to a different record
Navigated - (Classic ADO.NET only) Raised from mmBusinessForm.NavigateData after navigating to a different record.
PreSaving - Raised immediately before checking business rules.
Retrieving - Raised before retrieving an entity or entity list.
Retrieved - Raised after retrieving an entity or entity list.
Saving - Raised after checking business rules and before saving an entity or entity list.
Saved - Raised after saving an entity or entity list.
BrokenRulesWarnings - Raised when adding a broken rule or warning to the rule object's collection.

MM .NET Built-in Event Handling

When learning how to create an event handler for business object events, it's good to look at the event handling that's already built into MM .NET. Looking at how these event handlers work will give you a good idea of how you can build your own event handlers.

In most applications, the primary consumer of business object events are other business objects. For example, you may have an OrderDetail business object that is interested in events raised by an Order business object. Whenever the Order business object (the parent) retrieves an order record you may want the OrderDetail object (the child) to be automatically notified (and passed the primary key of the current order), and to automatically retrieve all order items associated with the order.

MM .NET allows you to register child business objects with parent business objects by means of the RegisterChildBizObj method discussed below. Using our example, you could register the OrderDetail business object as a child of the Order business object.

The following UML sequence diagram illustrates how the event model works between parent and child business objects when retrieving data:

In this diagram, when the Order business object's GetEntity method is called, it first calls OnStateChange to raise a "Retrieving" StateChange event. In response, the OrderDetail object's StateChangeHandler receives the event and calls its HookParentRetrieving method which, in this case, doesn't contain any code to respond to this particular state change (See the What is A Hook Method? section below for a brief overview of hook methods).

Next, the Order business object calls its associated data access object's GetEntity method which retrieves an order entity. Afterwards, it calls OnStateChange again, this time to raise a "Retrieved" StateChange event. In response, the OrderDetail object's StateChangeHandler receives the event and calls its HookParentRetrieved method. In this case, the hook method contains a call to the OrderDetail object's GetOrderItemsByOrderID method which retrieves all orders for the specified order id.

Using the ParentKeyValue Business Object Property

For the sake of convenience, when the StateChangeHandler method handles a parent business object event, it automatically saves the value of the parent business object's primary key in the ParentKeyValue property. You can access this primary key value from hook methods or from any other method in your business object.

Registering Child Business Objects

To register one business object as an event handler of another business object, you can call the RegisterChildBizObj method of the parent object, passing a reference to the child business object.

Here's some sample code that demonstrates this with an Order and OrderDetail business object:

In C#:

Order order = new Order();
OrderDetail orderDetail = new OrderDetail();
order.RegisterChildBizObj(orderDetail);

In VB .NET:

Dim order As New Order()
Dim orderDetail As New OrderDetail()
order.RegisterChildBizObj(orderDetail)

The first line of code instantiates the Order business object, and the second line of code instantiates the OrderDetail object. The last line of code calls the Order object's RegisterChildBizObj method with a reference to the OrderDetail object.

From this point on, any time the Order object raises a state change event, the OrderDetail object receives notification. Behind the scenes, the OrderDetail's StateChangeHandler event is called, and receives the two parameters passed by the Order object - a reference to the Order object, and an instance of mmBusinessStateChangeEventArgs.

For more information, check out the help topic Establishing Business Object Relationships.

Creating Custom Event Handlers for Business Object Events

At times you may want your own custom objects (other than business objects) to respond to business object events. To do this you need to:

Create an event handler method on your custom object.
Register your custom object with the business object's StateChange event.

Creating an Event Handler Method

The event handler method you create on your custom object must have the following signature:

In C#:

public virtual void MyStateChangeHandler(ImmBaseBusinessObject bizObj, mmBusinessStateChangeEventArgs e)

In VB .NET:

Public Overridable Sub MyStateChangeHandler(bizObj As ImmBaseBusinessObject, e As mmBusinessStateChangeEventArgs)

You can place custom code in these methods that handles any or all of the state change events raised by a parent business object.

Registering your Custom Object

Here is some sample code that show you how to register your custom object's StateChangeHandler method with a business object's StateChange event.

In C#:

MyCustomObject myCustomObject = new MyCustomObject();
order.StateChange += new mmBusinessStateChangeDelegate(myCustomObject.MyStateChangeHandler);

And in VB .NET:

Dim myCustomObject = New MyCustomObject()
AddHandler order.StateChange, AddressOf myCustomObject.MyStateChangeHandler

In these examples, the first line of code instantiates the custom object, and the second line of code registers the object's MyStateChangeHandler method with the Order business object.

Determining the Last Parent State Change

If you want to find out the last parent state change event, check the child business object's ParentState property.

Temporarily Turning Off the Raising of State Change Events

If you want to temporarily turn off the raising of State Change events, you can set the business object's AutoRaiseStateChangeEvents property to false. When this property is false no State Change events are raised when you retrieve, update, manipulate or navigate data.