Business Processors

When a Data Abstract service's UpdateData method is called, each of the deltas sent by the client are handed to a specific Business Processor¹ (which was either created automatically or explicitly dropped on the service at design time), which executes the appropriate INSERT, DELETE and UPDATE SQL commands for each of the changes related to one data table.

You can specify which data table a Business Processor refers to by setting the ReferencedDataTable property.

Business Processors can either auto generate the SQL used by such commands (see the AutoGenerateInsert, AutoGenerateDelete and AutoGenerateUpdate properties) or reference the commands that you define in a schema (InsertCommandName, DeleteCommandName and UpdateCommandName properties).

Once a DeltaChange has been processed, the contents of the row can be re-read through the use of a query identified by the RefreshDataTableName. This is useful whenever a trigger modifies the record in the background and you want to avoid a second round trip to the server to get an exact snapshot of the data. The values returned by the refreshed query are merged in the delta and sent back to the client during the same UpdateData call.

In order to control what happens before and after the processing of each delta or their changes, use the many events provided by the Business Processor class. Using such events, you can implement your custom server-side business logic.

The main goal of the Business Processor component is to provide the event handlers for implementing your server-side business logic. The most important events being the following:

event BeforeProcessDelta: DeltaEventHandler;
event AfterProcessDelta: DeltaEventHandler;
event BeforeProcessChange: DeltaChangeEventHandler;
event AfterProcessChange: DeltaChangeEventHandler;

property OnBeforeProcessDelta: TDAProcessDeltaEvent
      read fOnBeforeProcessDelta
      write fOnBeforeProcessDelta;

property OnAfterProcessDelta: TDAProcessDeltaEvent
      read fOnAfterProcessDelta
      write fOnAfterProcessDelta;

property OnBeforeProcessChange: TDABeforeProcessChangeEvent
      read fOnBeforeProcessChange
      write fOnBeforeProcessChange;

property OnAfterProcessChange: TDAAfterProcessChangeEvent
      read fOnAfterProcessChange
      write fOnAfterProcessChange;

During an update, the UpdateData method of the Data Abstract Service will iterate through the deltas collection that comes to the server and invokes the ProcessDelta method for each delta. This method will then iterate through each change contained in the delta. Events, as mentioned above, allow you to control each update and either ignore it, raise exceptions, or accept it as valid.

C#

private void bpCustomers_BeforeProcessChange(BusinessProcessor aSender, DeltaChangeEventArgs aEA)
{
  if (aEA.DeltaChange.Type!=ChangeType.Delete) return;

  string custID = Convert.ToString(aEA.DeltaChange.OldValues["CustomerID"]);
  IDbCommand cmd = ServiceSchema.NewCommand(Connection,
                           "GetOrderCount",
                           new string[] { "CustomerID" },
                           new object[] { custID });
  Int32 orderCount = Convert.ToInt32(cmd.ExecuteScalar());

  if (orderCount>0) {
    throw new Exception(String.Format("Cannot delete customer {0}. This customer has {1} orders",
      new object[] {custID, orderCount}));
  }
}

After a change is processed, it's removed from the delta by default. If you don't want this to happen and need to send back additional information to the client, you can attach code to the OnAfterProcessChange event handler:

C#

private void bpCustomers_AfterProcessChange(BusinessProcessor aSender, DeltaChangeEventArgs aEA)
{
  if (aEA.DeltaChange.Status == ChangeStatus.Resolved)
    aEA.DeltaChange.Message = "Processed just fine!";
  else
    aEA.DeltaChange.Message = "Something went wrong? " + aEA.DeltaChange.Message;

  aEA.CanRemove = False;
}

Note: Any delta processing in Data Abstract is handled via the Business Processor component, even if one wasn't specified during the application's design. When a delta arrives at the server and the server doesn't have an appropriate Business Processor available it will be created with default settings. This behavior of Data Abstract allows us to unify the updating process.

Footnotes