When the business object handler obtains a Retrieve verb from the request business object, it must ensure that an existing application entity, whose type is indicated by the business object definition, is retrieved, as follows:
For the Retrieve verb, the business object handler obtains the key value (or values) from the request business object. These key values uniquely identify an application entity. The business object handler then uses these key values to retrieve all the data associated with an application entity. The connector retrieves the entire hierarchical image of the entity, including all child objects. This type of retrieve operation might be referred to as an after-image retrieve.
An alternative way of retrieving data is to query using a subset of non-key attribute values, none of which uniquely define a particular application record. This type of retrieve processing is performed by the RetrieveByContent verb method. For information on retrieving by non-key values, see "Handling the RetrieveByContent verb".
This section provides the following information to help process a Retrieve verb:
The following steps outline the standard processing for a Retrieve verb:
A typical Retrieve operation can use one of the following methods:
The goal of each of these approaches is the same: Start with the top-level business object and rebuild the complete business object hierarchy. This type of implementation ensures that all children in the request business object that are no longer in the database are removed and are not passed back in the response business object. This implementation also ensures that the hierarchical response business object exactly matches the database state of the application entity. At each level, the Retrieve operation rebuilds the request business object so that it accurately reflects the current database representation of the entity.
In a Retrieve operation, an integration broker requests the complete set of data that is associated with an application entity. The request business object might contain any of the following:
Figure 27 shows a request business object for a Contact entity. The Contact business object includes a multiple cardinality array for the ContactProfile attribute. In this request business object, the ContactProfile business object array includes two child business objects.
Figure 27. Example
business object content for a Retrieve request
Application tables associated with the Contact and ContactProfile business objects might look like the tables in Figure 28.. This illustration also shows the foreign-key relationship between the tables. As you can see, the contact_profile table has a row for the ContactId of 100 that is not reflected in the Contact request business object in Figure 26..
Figure 28. Foreign-key
relationships between tables
The Retrieve operation uses the primary key in the Contact business object (100) to retrieve the data for the simple attributes in the response business object: values for the Name and JobTitle attributes. To be sure that it retrieves the correct number of child business objects, the verb operation must either create a new business object or prune child objects from the existing request business object. For the tables in Figure 28,, the Retrieve operation would need to create a new ContactProfile business object for the contact_profile row with a profile_id value of 277. In this way, the Retrieve operation properly creates and populates all arrays based on the current state of the application entities.
To retrieve entities associated with the top-level entity, the Retrieve operation might be able to use the application API:
If the attribute application-specific information in the business object definition contains information on foreign keys, the verb operation can use this information to generate command to access the application (such as SQL statements). For example, application-specific information for the foreign key attribute of the ContactProfile child business object might specify:
Figure 29 shows example application-specific information for the primary key attribute of the Contact business object and the primary and foreign key attributes of the ContactProfile child business object.
Figure 29. Foreign-key
relationships in business objects
Using the application-specific information, the verb operation can find the name of the child table (contact_profile) and the column for the foreign key (contact_id) in the child table. The verb operation can also find the value of the foreign key for the child business object by obtaining the value of the primary key attribute (ContactId) in the parent business object (100). With this information, the verb operation can generate a SQL SELECT statement that retrieves all the records in the child table associated with the parent key. The SELECT statement to retrieve the data associated with the missing contact_profile row might be:
SELECT profile_id, job_code, department FROM contact_profile WHERE contact_id = 100
The SELECT statement returns three rows from the example contact_profile table, as shown in Figure 30..
Figure 30. Results of
SELECT statement for example Retrieve operation
If a Retrieve operation returns multiple rows, each row becomes a child business object. The verb operation might process retrieved rows as follows:
The response business object for the Retrieve operation on the two example tables might look like Figure 31.. The verb operation has retrieved the current database entity and has added a child to the hierarchical business object.
Figure 31. Business object
response to example Retrieve request
By default, the Retrieve operation should return failure if it cannot retrieve application data for the complete set of child business objects in a hierarchical business object. However, you can implement the verb operation so that the behavior of the connector is configurable when one or more of the children in a business object are not found in the application.
To do this, define a connector-specific configuration property named IgnoreMissingChildObject, whose values are True and False. The Retrieve operation obtains the value of this property to determine how to handle missing child business objects. When the property is True, the Retrieve operation should simply move on to the next child in the array if it fails to find a child business object. In this case, the verb operation should return BON_VALCHANGE if it is successful in retrieving the top-level object, regardless of whether it is successful in retrieving its children.
The Retrieve operation should return one of the outcome-status values shown in Table 29.
Table 29. Possible outcome status for C++ Retrieve verb Processing