Handling the RetrieveByContent verb

An integration broker might need to retrieve a business object for which it has a set of attribute values without having the key attribute (or attributes) that uniquely identifies an application entity. Such a retrieve is called "retrieve by non-key values" or "retrieve by content." As an example, if a business object handler receives a Customer business object with the verb RetrieveByContent and with the non-key attributes Name and City set to Smith and San Diego, the RetrieveByContent operation can attempt to retrieve a customer entity that matches the values of the Name and City attributes.

When the business object handler obtains a RetrieveByContent 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:

This section provides the following information to help process a RetrieveByContent verb:

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

Implementation for a RetrieveByContent verb operation

RetrieveByContent functions the same as the Retrieve verb except that it uses a subset of non-key values, instead of key values, to retrieve application data. In its most robust implementation, a top-level business object and its child business objects would independently support the RetrieveByContent verb. However, not all application APIs enable retrieve by non-key values for hierarchical business objects.

A more common implementation is to provide RetrieveByContent support only in the top-level business object. When a top-level business object supports retrieve by non-key values and this retrieve-by-content is successful, the RetrieveByContent operation can retrieve the keys for the entity matching the request business object. The verb operation can then perform a Retrieve operation to retrieve the complete business object.

You might want to specify which attributes are to be used in RetrieveByContent operations. To do this, you can implement attribute application-specific information to specify those attributes that will contain a value that is to be used in the RetrieveByContent operation or receive a value as a result of the operation.

Outcome status for RetrieveByContent processing

The RetrieveByContent operation should return one of the outcome-status values shown in Table 30.

Table 30. Possible outcome status for C++ RetrieveByContent verb processing
RetrieveByContent condition C++ outcome status
If the RetrieveByContent operation finds a single entity that matches the query, 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 a "Value Changed" outcome status
BON_VALCHANGE
If the IgnoreMissingChildObject connector property is True, the RetrieveByContent 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. BON_VALCHANGE
If the RetrieveByContent operation finds multiple entries that match the query, it returns:
  • retrieves only the first occurrence of the match; this business object is returned to the connector framework through the request business object parameter.
  • fills a return-status descriptor with further information about the search
  • returns a status of "Multiple Hits" to notify the connector framework that there are additional records that match the specification
BON_MULTIPLE_HITS
If the RetrieveByContent operation does not find matches for retrieve by non-key values, it:
  • fills a return-status descriptor containing additional information about the cause of the RetrieveByContent error
  • returns a "RetrieveByContent Failed" outcome status
BON_FAIL_RETRIEVE_BY_CONTENT

Note:
When the connector framework receives the BON_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