Handling the Retrieve verb

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:

Note:
For a table-based application, the entire application entity must be retrieved from the application database.

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.

Important:
All connectors must implement a doVerbFor() method with verb processing for the Retrieve verb. This requirement holds even if your connector will not perform request processing.

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:

Note:
You can modularize your business object handler so that each supported verb is handled in a separate Java method. If you follow this structure, a Retrieve method handles processing for the Retrieve verb.

Standard processing for a Retrieve verb

The following steps outline the standard processing for a Retrieve verb:

  1. Create a new business object of the same type as the request business object. This new business object is the response business object, which will hold the retrieved copy of the request business object.
  2. Set the primary keys in the new top-level business object to the values of the top-level keys in the request business object.
  3. Retrieve the application data for the top-level business object and fill the response top-level business object's simple attributes.
  4. Retrieve all the application data associated with the top-level entity, and create and fill child business objects as needed.

Note:
By default, the Retrieve method returns failure if it cannot retrieve application data for all the child objects in a hierarchical business object. This behavior can be made configurable; for information, see "Configuring a Retrieve to ignore missing child objects".

Implementation of a Retrieve verb operation

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.

Example: Retrieve operation

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 29 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 29. 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 30. 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 28.

Figure 30. 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 30, 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.

Retrieving child objects

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 31 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 31. 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 32.

Figure 32. 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:

  1. For each row, create a new child business object of the correct type.
  2. Set attributes in the new child business object based on the values that a SELECT statement returns for the associated row.
  3. Recursively retrieve all children of the child business object, creating the business object and setting the attributes for each one.
  4. Insert the array of child business objects into the multiple-cardinality attribute in the parent business object.

The response business object for the Retrieve operation on the two example tables might look like Figure 33. The verb operation has retrieved the current database entity and has added a child to the hierarchical business object.

Figure 33. Business object response to example Retrieve request


Configuring a Retrieve to ignore missing child objects

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 VALCHANGE if it is successful in retrieving the top-level object, regardless of whether it is successful in retrieving its children.

Outcome status for Retrieve verb processing

The Retrieve operation should return one of the outcome-status values shown in Table 35.

Table 35. Possible outcome status for Java Retrieve verb processing

Retrieve condition Java outcome status
When the Retrieve operation is successful, it:
  • fills the entire business object hierarchy, including all child business objects; this business object is returned to the connector framework through the request business object parameter.
  • returns the "Value Changed" outcome status to indicate that the connector has changed the business object
VALCHANGE
If the IgnoreMissingChildObject connector property is True, the Retrieve operation returns the "Value Changed" outcome status for the business object if it is successful in retrieving the top-level object, regardless of whether it is successful in retrieving its children. VALCHANGE
If the entity that the business object represents does not exist in the application, the connector returns a special outcome status instead of "Fail". BO_DOES_NOT_EXIST
If the request business object does not provide a key for the top-level business object, the Retrieve operation can take either of the following actions:
  • Fill a return-status descriptor with information about the cause of Request failure and return a "Fail" outcome status.
  • Call the RetrieveByContent method to retrieve using the content of the top-level business object.
FAIL

Note:
When the connector framework receives the VALCHANGE outcome status, it includes a business object in its response to InterChange Server. For more information, see Sending the verb-processing response.

Copyright IBM Corp. 1997, 2003