Configuration Session Change Tracking

This chapter describes the CIO’s Configuration Delta API for tracking changes that have been made to regions of your user interface during a configuration session.

This chapter covers the following topics:

Introduction to Configuration Session Change Tracking
How Change Tracking Works
Starting a Session
Tracking Session Changes
Updating a Region
Handling Screen Changes
Creating a Custom DeltaValidator
Unified Code Example for Change Tracking

Introduction to Configuration Session Change Tracking

This section is divided as follows:

For a general overview of the Configuration Delta API, see How It Works.
For examples of how the Configuration Delta API is used, see:
For information on a specialized customization topic, see Creating a Custom DeltaValidator.
For detailed reference documentation that describes the classes of the Configuration Delta API, see Reference Documentation for the CIO.

You can use the CIO’s Configuration Delta API to query a Configuration object about changes (deltas) that have been made to the configuration during the current configuration session.

Note: Although the functionality described in this section uses the terms delta and tracking, this functionality is distinct from the tracking of deltas described in the Oracle Telecommunications Service Ordering Process Guide. In that document, the term delta refers to a change made to a configuration relative to an instance of that configuration residing in an installation repository.

The Configuration Delta API provides a unified interface that enables you to track deltas only on the specific nodes in which you register interest. Contrast this to the set of methods listed Change-Detection Methods for the Configuration Object, which provide change information only for the entire set of the nodes in a configuration.

Change-Detection Methods for the Configuration Object

Configuration.getSelectedItems()
Configuration.getUnsatisfiedItems()
Configuration.getUnsatisfiedItems()
Configuration.getUnsatisfiedRuleMessages()
Configuration.getValidationFailures()

How Change Tracking Works

Note: This use of the CIO is intended for both custom applications and Configurator Extensions.

Both custom applications and Configurator Extensions can be clients of the Configuration Delta API.

The Configuration Delta API consists of the classes and interfaces in the CIO listed in the table Classes and Interfaces for the Configuration Delta API. The Instances column indicates how many instances of the class exist at runtime, during a configuration session.

Classes and Interfaces for the Configuration Delta API
Class or Interface	Role	Instances
DeltaManager	Manages all changes made by end user actions during a configuration session. See Role of the DeltaManager.	One per client.
DeltaRegion	Maintains list of watched runtime nodes and changes to be tracked on those nodes. See Role of DeltaRegions.	One per each region of interest in the user interface. Can register multiple DeltaValidators, one for each type of change to be tracked.
DeltaValidator	Manages all defined types of changes. Base class for all DeltaValidators. See Role of DeltaValidators.	One per each type of change to be tracked. Can be registered with multiple DeltaRegions.
IValidatorChange	Represents any change type. See Role of the IValidatorChange Interface.	Not instantiated. Implemented by all DeltaValidators.

Relationship of the Classes

The diagram in Example Class Relationships in the Configuration Delta API shows the relationship of the classes in the Configuration Delta API, using a typical example of their use.

Example Class Relationships in the Configuration Delta API

the picture is described in the document text

In Example Class Relationships in the Configuration Delta API, the DeltaManager is managing a UI containing three DeltaRegions (labeled 1, 2, and 3).

Each DeltaRegion maintains a list of runtime nodes that are watched for changes (the watched-nodes list).
Each DeltaRegion is registered with the DeltaManager and contains a list of DeltaValidators, which determine the types of changes that are watched in the region.
In the example:
- DeltaRegion 1 has registered DeltaValidators 1 and 2
- DeltaRegion 2 has registered DeltaValidators 2, 3, and 4
- DeltaRegion 3 has registered DeltaValidators 4 and 5
Each DeltaValidator can be registered with multiple DeltaRegions. Each DeltaValidator watches for a particular change type in a combined list of all the runtime nodes in all the DeltaRegions that it is registered with.
In the example:
- Since DeltaValidator 1 is registered only with DeltaRegion 1, its watched-nodes list is the same as the watched-nodes list in DeltaRegion 1.
- DeltaValidator 2 is registered with two DeltaRegions (1 and 2). Hence, its watched-nodes list is the union of the watched-nodes lists from both DeltaRegions 1 and 2.

Role of the DeltaManager

The DeltaManager object is instantiated once, at the beginning of a configuration session, and is cached on the Configuration object for the session. The DeltaManager manages all the changes made by end user actions during that session.

The DeltaManager is identified by an ID that is passed to the method that creates it, Configuration.createDeltaManager().

You can register multiple DeltaRegions with the DeltaManager, to manage the regions of your client’s user interface.

Role of DeltaRegions

A DeltaRegion object represents a distinct portion of your client’s user interface. For example, your UI might have a navigation region, an update region, and a summary region; your client would create a DeltaRegion object for each of them.

Each DeltaRegion maintains a list of watched runtime nodes in that region. You determine which nodes are to be watched for changes by registering a DeltaRegion object with the DeltaManager, using the method DeltaManager.registerRegion(), which takes as arguments the list of nodes to watch, the list of DeltaValidators to watch them with, and an ID. See Registering a DeltaRegion: All Nodes for an example of registering a region.

Role of DeltaValidators

A DeltaValidator object manages defined types of changes. A DeltaValidator can be thought of as a reusable software component that reports on a particular type of change.

Each particular change type is handled through a specialized subclass of the class DeltaValidator. The CIO provides a set of default change types that correspond to the types of changes that can be made through the CIO. Each subclass defines a change object (in the form of an inner class) that implements methods that provide information about the specified type of change.

The table Default Change Types and Their Change Objects lists a sampling of the default change types, and the specialized DeltaValidators that represent them. For details on the methods of these change object classes, and the complete set of DeltaValidator subclasses, see the CIO reference documentation described in Reference Documentation for the CIO.

You can write custom DeltaValidators for change types that are not already provided by the CIO. For details, see Creating a Custom DeltaValidator.

Default Change Types and Their Change Objects
Change Type	Class for Change Object
ATP (Availability to Promise)	AtpDeltaValidator.AtpChange
Availability (for selection)	AvailabilityDeltaValidator.AvailabilityChange
Connection	ConnectionDeltaValidator.ConnectionChange
Count (of runtime nodes)	CountDeltaValidator.CountChange
Deletion	DeletionDeltaValidator.DeletionChange
Price	PriceDeltaValidator.PriceChange
Selection status (change between selected and deselected)	SelectionDeltaValidator.SelectionChange
Logic state (of a node)	StateDeltaValidator.StateChange
Satisfaction (change between satisfied and unsatisfied)	UnsatisfactionDeltaValidator.UnsatisfactionChange
ValidationFailure messages	ValidationDeltaValidator.ValidationChange

Each change object (inner class) implements the method getType() of the interface IValidatorChange. Each inner class must also implement any methods that are appropriate to their particular change type. See Custom Method to Update a Region for examples of how you would use both the IValidatorChange methods and the type-specific methods.

Role of the IValidatorChange Interface

The IValidatorChange interface:

Represents any kind of DeltaValidator change. It is implemented by all DeltaValidators to represent their specific change object.
Is the interface for the class ValidatorChange, which is the base class for all the change-object inner classes described in Role of DeltaValidators.
Provides the method getType(), which returns one of the DeltaValidator type constants defined in the DeltaValidator object. See Custom Method to Update a Region for an example of how you would use this method.

Starting a Session

Your client should perform the following steps once, at the beginning of a configuration session.

Create a Configuration object.

See Creating a Configuration Object in Creating a Configuration Object.
Create a DeltaManager object and associate it with the Configuration object.

See Associating a DeltaManager with a Configuration in Associating a DeltaManager.
Specify the DeltaValidators corresponding to the change types you want to track during the configuration session.

See Specifying DeltaValidators in Specifying DeltaValidators.
Get a list of the nodes in the region whose changes you are interested in tracking and register that region.

See Registering a DeltaRegion: All Nodes or Registering a DeltaRegion: Subset of Nodes in Registering DeltaRegions.

Creating a Configuration Object

If you are working with a custom application, create a Configuration object, as described in see Creating Configurations for required background information. See especially Creating a Configuration Object (MyConfigCreator.java).

Creating a Configuration Object

...
// Create a new Configuration and DeltaManager
ConfigParameters params = new ConfigParameters(modelId);
Configuration config = cio.startConfiguration(params, context);
...

Note: The fragmentary code examples in this section are meant to be read together, as parts of a larger example. Identifiers are shared between examples; where the same identifier occurs in multiple examples, it refers to the same object. These fragmentary examples are assembled together in Tracking Session Changes (DeltaExample.java).

Associating a DeltaManager

Associate a DeltaManager object with the Configuration object for the current configuration session.

Associating a DeltaManager with a Configuration

...
DeltaManager deltaMgr = config.createDeltaManager("MyDeltaMgr");
...

Specifying DeltaValidators

Create DeltaValidator objects for the change types that you want to track during the configuration session. Then add them to a list that can be used to register the DeltaValidators for a DeltaRegion (shown in Registering a DeltaRegion: All Nodes).

Specifying DeltaValidators

...
// Create a Navigation (Tree) region. This is interested in watching
// all runtime nodes for instance name, instantiation, and unsatisfaction
// changes.
List dvList = new ArrayList();
dvList.add(deltaMgr.getDeltaValidator(DeltaValidator.INSTANCE_NAME_DV));
dvList.add(deltaMgr.getDeltaValidator(DeltaValidator.INSTANTIATION_DV));
dvList.add(deltaMgr.getDeltaValidator(DeltaValidator.UNSATISFACTION_DV));
...

Registering DeltaRegions

Register a DeltaRegion with the DeltaManager, passing it the list of nodes to watch and the list of DeltaValidators to watch them with (dvList, defined in Specifying DeltaValidators).

You can also register an individual DeltaValidator, using DeltaManager.registerDeltaValidator().

Registering a DeltaRegion: All Nodes shows the registration of a region using all of the runtime nodes in the Configuration (config.getRuntimeNodes()). If you want to use some subset of the runtime nodes (such as only the nodes visible in the user interface), then you must implement a custom method to do so. This alternative is shown in Registering a DeltaRegion: Subset of Nodes, using the hypothetical custom method getRuntimeNodesInSelectedComponent().

Registering a DeltaRegion: All Nodes

...
List watchedNodes = config.getRuntimeNodes();
DeltaRegion treeRegion = deltaMgr.registerRegion(watchedNodes, dvList, "MyTreeRegion");
...

Registering a DeltaRegion: Subset of Nodes

...
// Create a component region. This region displays a Component screen and is
// interested in watching all nodes in that component for availability, count,
// price, state and unsatisfaction changes
dvList.clear();
dvList.add(deltaMgr.getDeltaValidator(DeltaValidator.AVAILABILITY_DV));
dvList.add(deltaMgr.getDeltaValidator(DeltaValidator.COUNT_DV));
dvList.add(deltaMgr.getDeltaValidator(DeltaValidator.PRICE_DV));
dvList.add(deltaMgr.getDeltaValidator(DeltaValidator.STATE_DV));
dvList.add(deltaMgr.getDeltaValidator(DeltaValidator.UNSATISFACTION_DV));

watchedNodes = getRuntimeNodesInSelectedComponent(); // a custom method, not defined here

DeltaRegion compRegion = deltaMgr.registerRegion(watchedNodes, dvList, "MyCompRegion");
...

Tracking Session Changes

Your client should perform the following steps each time it needs to track a session change to the current configuration. Most of the code examples shown in this section are shown in a more complete context in Tracking Session Changes (DeltaExample.java).

Begin a configuration transaction. See Using Logic Transactions for background.
```
ConfigTransaction tran = config.beginConfigTransaction();
```

Perform the change, by making an assertion. For background details, see Getting and Setting Logic States and Getting and Setting Numeric Values. The following example fragment shows how to select the Option node named Option1.

// Make an assertion to change the current configuration
try { 
Option option1 = (Option)config.getRootComponent().getChildByName("Feature").getChildByName("Option1");
option1.select();
 } catch (LogicalException loe) { }

Close the configuration transaction.
```
config.commitConfigTransaction(tran); 
```
Query the configuration for the changes of interest. Update the list of changes that you can use to update a region that you registered. The following example updates the change map for the region registered in Registering a DeltaRegion: All Nodes.
```
// Get the deltas due to this assertion and update the tree and component regions
Map treeChanges = deltaMgr.getUpdateMapForRegion("MyTreeRegion");
```
Update the region that you registered (as in Registering a DeltaRegion: All Nodes), using a custom method. The custom method updateTreeRegion() is described in Updating a Region.
```
// Now update the tree region cache and UI with treeChanges
updateTreeRegion(treeChanges);
```

Updating a Region

When you need to update a region with the a list of the changes that your client has been tracking with the DeltaManager, you can invoke a custom method such as updateTreeRegion(), whose definition is shown in Custom Method to Update a Region. This method operates as follows:

Take as an argument the changes object that is a Map of the changed nodes in the registered region (MyTreeRegion). See Tracking Session Changes for a description of when this updating takes place.

The map of changed nodes consists of a set of pairs, in which the key is a RuntimeNode object, and the value is a collection of IValidatorChange objects.
Iterate over the nodes in the Map of changed nodes. Use a custom method, such as getUiNode() in the example, to get access to the UI node corresponding to the changed node object.
Iterate over the List of changes for the node, using each change to set the value of the IValidatorChange object change.
For each change, call IValidatorChange.getType(), which returns the type of the change in a form that corresponds to one of the change types defined in the class DeltaValidator, such as INSTANCE_NAME_DV.
Using a switch control structure, switch on the change type. For each change type, cast the change object to the actual implementing class of the change, such as InstanceNameChange.
```
InstanceNameDeltaValidator.InstanceNameChange nameChange = InstanceNameDeltaValidator.InstanceNameChange)change;
```
Using the particular change object for the change, use a custom method to update the UI node corresponding to the changed node object.
```
String newName = nameChange.getInstanceName();
uiNode.setName(newName); // custom method on uiNode
```

Custom Method to Update a Region

public static void updateTreeRegion(Map changes) {
  for (Iterator iter = changes.keySet().iterator(); iter.hasNext();) {
    RuntimeNode changedNode = (RuntimeNode)iter.next();
    uiNode = getUiNode(changedNode); // custom method
    Collection nodeChanges = (Collection)changes.get(changedNode);
    for (Iterator iter2 = nodeChanges.iterator(); iter2.hasNext();) {
      IValidatorChange change = (IValidatorChange)iter2.next();
      switch (change.getType()) {
        case DeltaValidator.INSTANCE_NAME_DV:
          InstanceNameDeltaValidator.InstanceNameChange nameChange = InstanceNameDeltaValidator.InstanceNameChange)change;
          String newName = nameChange.getInstanceName();
          uiNode.setName(newName); // custom method on uiNode
          break;
        case DeltaValidator.INSTANTIATION_DV:
          InstantiationDeltaValidator.InstantiationChange iChange = (InstantiationDeltaValidator.InstantiationChange) change;
          Collection added = iChange.getNewlyAddedInstances();
          Collection deleted = iChange.getNewlyDeletedInstances();
          uiNode.updateInstances(added, deleted); // custom method on uiNode
          break;
        case DeltaValidator.UNSATISFACTION_DV:
          UnsatisfactionDeltaValidator.UnsatisfactionChange uChange = (UnsatisfactionDeltaValidator.UnsatisfactionChange) change;
          boolean unsatisfied = uChange.isUnsatisfied();
          uiNode.setUnsatisfied(unsatisfied); // custom method on uiNode
          break;
      }
    }
  }

Handling Screen Changes

When a screen change (such as a screen flip to another UI page) occurs in your client’s user interface, you should update the list of watched nodes in each DeltaRegion, so that you can get a list of the changes made to the nodes whenever you need such a list.

The manner in which you update the watched nodes depends on how extensive are the changes to the region you are watching.

If the general layout of the region is unchanged, and only the set of nodes in the region may have changed, you can simply clear the list of watched nodes, get the list of currently interesting nodes, then add that list to the region’s list of nodes to watch. This approach is shown in Updating Watched Nodes: Screen Format Unchanged .

Updating Watched Nodes: Screen Format Unchanged
```
...
rgn1.clearWatchedNodes(); 
List visibleNodes = getCurrentVisibleNodes(); // custom method
rgn1.addWatchedNodes(visibleNodes); 
...
```
You must define the custom method used to get the visible nodes, getCurrentVisibleNodes().
If the general layout of the region has changed significantly, then you should unregister the region, rebuild the list of DeltaValidators, and register the region, specifying all the nodes and the list of DeltaValidators. This approach is shown in Updating Watched Nodes: Screen Format Changed Significantly.

Updating Watched Nodes: Screen Format Changed Significantly
```
...
mgr.unRegisterRegion(rgn1.getId()); 
List dvList = new ArrayList(); 
dvList.add(dm.getDeltaValidator(DeltaValidator.PRICE_DV)); 
dvList.add(dm.getDeltaValidator(DeltaValidator.AVAILABILITY_DV)); 
rgn1 = mgr.registerRegion(config.getRuntimeNodes(), dvList, null); 
...
```

Creating a Custom DeltaValidator

It is possible, but unlikely, that you may need to write custom DeltaValidators for change types that are not already defined in the CIO. See Role of DeltaValidators for an explanation of DeltaValidators and a description of the default DeltaValidators provided with the CIO.

In order to create a custom DeltaValidator, you must do the following:

Define a subclass that extends DeltaValidator. This class is your custom DeltaValidator. For example:

public class MyCustomDeltaValidator extends DeltaValidator {
  // constructor
  protected MyCustomDeltaValidator() {
    setType(MY_CUSTOM_DV);
  }

Define a change object that represents the type of change that your custom DeltaValidator is designed to track. This change object class must implement the interface IValidatorChange. See Role of the IValidatorChange Interface.
```
public class MyCustomChange extends ValidatorChange {
// Implement your change object here
}
```
In the DeltaValidators defined in the CIO, the change object is defined as an inner class, but this design decision is not mandatory.
In the custom DeltaValidator, define a constant that designates your custom type of DeltaValidator and the change type that it tracks. The value of the constant must be greater than DeltaValidator.CUSTOM_DV (which is currently defined as 1000, though you should not directly reference that value). Example:
```
public static final int MY_CUSTOM_DV = DeltaValidator.CUSTOM_DV + 1;
```
In the custom DeltaValidator, implement the method isChanged(), which is defined as abstract in DeltaValidator:
```
protected abstract boolean isChanged(IRuntimeNode node, DeltaRegion region)
```
Your implementation must determine if there are any changes to be reported for the runtime node by this DeltaValidator, for the given region.

In the custom DeltaValidator, implement the method getChange(), defined as abstract in DeltaValidator:

protected abstract IValidatorChange getChange(IRuntimeNode node, DeltaRegion region)

Your implementation must get the change object for this node. For example:

protected IValidatorChange getChange(IRuntimeNode node, DeltaRegion region) {
  MyCustomChange change = new MyCustomChange();  return change;
}

In the change-object class, implement the method getType() from the interface IValidatorChange. Your implementation must return the change type, which corresponds to the custom DeltaValidator type that you defined. For example:
```
public int getType() {
  return MyCustomDeltaValidator.MY_CUSTOM_DV;
}
```
Include your custom DeltaValidator in list of DeltaValidators passed to DeltaManager.registerRegion(). See Registering DeltaRegions. You can also register a custom DeltaValidator independently, using DeltaManager.registerDeltaValidator(), which adds a DeltaValidator to the list of existing ones. This will enable different regions to use the same instance of your custom DeltaValidator.

Unified Code Example for Change Tracking

The code in Tracking Session Changes (DeltaExample.java) assembles together the fragmentary examples shown elsewhere in this chapter.