Propagation Processing

When a row of data changes for a table which is configured for Entity rule objects, then the Entity Rule Object Propagator requests the corresponding rule object and manipulates it in memory.

A rule object may be created, modified or removed, according to the nature of the change to the underlying database row (and taking into account configurations for logical deletions and/or filters).

The Entity Rule Object Propagator informs the Dependency Manager of any rows that have changed so that the Dependency Manager can determine the effects of those changes. Dependencies on entity data are stored at the entity row level, by recording a dependency on the entity's name and the row's key value.

Each database row may map to a number of target rule classes, according to the configurations for the Entity Rule Object Propagator held on the system. However, for the sake of clarity, the rest of this section describes the behavior of the Entity Rule Object Propagator in the situation where an entity is configured to be propagated to a single rule class only.

Support for Entity Operation Stereotypes

Cúram database tables are modeled as entities in the application model. Each modeled entity may contain several database operations, each with their own stereotype. Not all of these operations stereotypes can be reliably propagated. The table below shows the support for propagating data from invocations of methods for these stereotypes:

Table 1. Support for Entity Operation Stereotypes
Entity Operation Stereotype	Support in Entity Rule ObjectPropagator
(unstereotyped)	Ignored - no data written.
batchinsert	Supported. Each row in the batch will be propagated, if possible (as per nsinsert).
batchmodify	Supported¹. Each row in the batch will be propagated, if possible (as per nsmodify).
insert	Supported.
modify	Supported.
nkmodify	Supported.
nkread	Ignored - no data written.
nkreadmulti	Ignored - no data written.
nkremove	Supported.
ns	For read operations, ignored. For write operations, not supported, as the operation can contain arbitrary SQL and in general it is not possible to reliably detect which database rows have been affected by the operation.
nsinsert	Supported, as long as the details being written to the database include a value for the primary key (i.e. no reliance on database-level key assignment).
nsmodify	Supported.
nsmulti	Ignored - no data written.
nsread	Ignored - no data written.
nsreadmulti	Ignored - no data written.
nsremove	Supported.
read	Ignored - no data written.
readmulti	Ignored - no data written.
remove	Supported.
²

Any operation that has the "no generated SQL" option set will not be supported by the rule object propagators included with the application.

If the EntityRuleObjectPropagator detects that an unsupported operation has occurred, then its behavior is governed by the value of the curam.ruleobjectpropagation.nonpropagatableoperation.errorlevel environment variable:

Table 2. Behavior when non-propagatable operations are invoked
Value of `curam.ruleobjectpropagation. nonpropagatableoperation.errorlevel`	Behavior of Entity Rule Object Propagator	Comments
warn (default value)	The Entity Rule Object Propagator writes a warning to the application logs.	This is the default behavior and should be suitable for most environments.
ignore	The Entity Rule Object Propagator ignores the non-propagatable operation.	Consider using this setting if you have very many invocations of non-propagatable operations, and you already have in place procedures to identify and recalculate any dependents potentially affected.
error	The Entity Rule Object Propagator raises an exception with the details of the non-propagatable operation (which will typically result in the overall database transaction being rolled back).	Consider using this setting if you do not expect to have any non-propagatable operations.

If a non-propagatable operation occurs (and the Entity Rule Object Propagator is configured to warn the operator), then the operator should follow your procedures to identify and recalculate any dependents potentially affected.

The "Exclude" List for Entity Propagation

Some database tables are unsuitable for consideration by the Entity Rule Object Propagator because:

they contain non-business data only;
they have abnormally high numbers of data writes; and/or
access to their data occurs before the propagation framework has been initialized.

The application allows components to register such database tables on an "exclude" list, and writes to these database tables are never considered for propagation to the Dependency Manager. The application's components may contribute to the exclude list, and customers may add further entries to the list by adding a binding inside a Guice module as follows:

import com.google.inject.AbstractModule;
import curam.core.sl.infrastructure.propagator.impl.
    RuleObjectDatabaseWriteListener.ExcludedTable;

public class MyModule extends AbstractModule {

  // _______________________________________________________________
  @Override
  public void configure() {

    ...
    {
      // register excluded tables

      final Multibinder<ExcludedTable> excludedTables = Multibinder
          .newSetBinder(binder(), ExcludedTable.class);

      excludedTables
          .addBinding()
          .toInstance(
              new ExcludedTable(
                  curam.core.sl.infrastructure.assessment.intf.
                  MyEntity1.class));
      excludedTables
          .addBinding()
          .toInstance(
              new ExcludedTable(
                  curam.core.sl.infrastructure.assessment.intf.
                  MyEntity2.class));

    }
    ...

  }
}

For information on writing Guice modules, see the Persistence Cookbook.

¹ There is one edge-case which is not supported, which is where a batchmodify operation contains a number of modify operations, each of which change the primary key value of an entity, and which form a chain of changes to the same underlying row, e.g. the batchmodify contains two operations:

a modify which changes a row's key from keyValue1 to keyValue2; and
another modify which changes the same row's key from keyValue2 to keyValue3.

The net effect of these chained modify operations is to change the database row's key from keyValue1 to keyValue3. Such a change cannot be reliably propagated by the Entity Rule Object Propagator and should be avoided. (It is good practice to avoid creating modify operations that change a row's key anyway.)

² There is one edge-case which is not supported, which is where a batchmodify operation contains a number of modify operations, each of which change the primary key value of an entity, and which form a chain of changes to the same underlying row, e.g. the batchmodify contains two operations:

a modify which changes a row's key from keyValue1 to keyValue2; and
another modify which changes the same row's key from keyValue2 to keyValue3.