Object Data Synchronization: Fetches

The synchronization of object data is handled by fetch and push definitions, with the fetch being the primary definition for this purpose. A fetch defines how the Agentry Server synchronizes data for a target object collection. This object collection must be a top-level collection within the module. A fetch is made up of steps that retrieve the data for the collection from the back end system. These steps are grouped into three categories within the Fetch definition: Client Exchange Steps, Server Exchange Steps, and Removal Steps. A fetch may also include properties to store data captured from the user and validation rules for those property values. A fetch may also contain property and validation rule definitions, though this is a less common implementation option for fetches.

General Fetch Processing

During a transmit the Server processes all main fetches within the application. This is the primary distinction between main and non-main fetches. If a fetch is not a main fetch it will only be processed by the Server if the transmit step within the action on the client lists it as one to be processed. Regardless of whether or not a fetch is a main fetch, the behavior of a given fetch is the same when it is processed by the Agentry Server.

A part of fetch processing also includes a separate definition type, object read steps. The fetch targets an object collection within the module. The object definition can include object read steps. If the object type within the collection targeted by the fetch contains read steps, those steps are processed as the last part of the fetch processing. Note that read steps in any nested collection of the target collection of the fetch are not processed.

The order of processing the step usage definitions involved in fetch processing is:

Client Exchange Steps
Server Exchange Steps
Removal Steps
Object Read Steps

Each of these definition types references a back end step definition within the same module as the fetch. A fetch can contain multiple definitions of each of these types, with the order of execution defined within a given type defined by the developer.

The fetches of an application are the last synchronization definitions processed during transmit. For applications with multiple fetch definitions, the order in which each fetch is processed is undefined. Therefore each fetch definition should be defined to operate independently of any others within a given application.

Object Retrieval and Replacement Processing

When a fetch is processed during transmit, any step executed by a client exchange, server exchange, or object read step can return data to create new objects or replace existing objects. This process involves a step returning data from the back end system to the Agentry Server. The values of this data are named or identified according to the logic within the step. For example, a SQL step containing a select statement will return a data set of records. Each column in the return set is identified according to either the name of the database table from which it was retrieved, or according to any column alias for the values contained in the SQL statement. The Agentry Server then processes this data according to the following procedure:

During the transmit the Client provides the Server with the key property and last update value of any object instances currently contained in the object collection targeted by the fetch. These values are stored in an object collection in the Server’s memory that mirrors the collection on the Client. This occurs before the steps of the fetch are processed.
When a step within the fetch returns data, a value with the same name as the key property of the object is searched for in the return set. If such a value is not found then the data is discarded, as the Server cannot determine to which object the data belongs.
When the key property value is found, the Server compares this value with the key properties of any object instances it currently contains in the object collection.
1. If a match is found, any other data within the record is processed. Each value identified with the same name as property in the object is assigned to that matching property. If the object property contained a value prior to this processing, it is overwritten. This is object replacement processing.
2. If a match between the return set’s key property and an existing object instance, a new object is instantiated by the Server and stored in the collection. The remaining values in within the record is processed, with each value identified with the same name as a property in the object assigned to that matching property. Any properties within the object that do not have a value in the return set are initialized to null. Any values in the return set that do not have a match in the object properties are discarded.
This process repeats for each step executed as a part of fetch processing that returns data. When the fetch step usage definitions and object read steps have all been executed, the Server sends down any new or replaced objects to be stored in the object collection on the Client.

Object Removal Processing

In addition to retrieving object data, the fetch processing can also result in the removal objects from the Client. When a removal step returns a value identified as the key property for the object type being synchronized, the Server will send this value to the Client with the indication that it should be removed from the collection property. The removal step should normally only ever return the key property value, as any other data returned is not used by the Server and therefore unnecessary.

When an object is deleted from the Client it is important to keep in mind that the objects stored in any nested collections are also removed. Remember that these child objects are data for the parent object and, just as any other property would, they are removed with the parent object.

The order of processing during a transmit is such that, if an object is to be removed as the result of fetch processing, any data captured on the client in transaction definitions targeting the fetch will have already been processed. No data captured on the client is lost as a result of a fetch removing the object, as the transaction will have already been processed and, presumably, updated any captured values to the back end system.