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 Java 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 37..

Table 37. Possible outcome status for Java RetrieveByContent verb processing

RetrieveByContent condition Java 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
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. VALCHANGE
If the RetrieveByContent operation finds multiple entries that match the query, it:
  • 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
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
RETRIEVEBYCONTENT_FAILED

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, 2004