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:
- For a
flat business object, the RetrieveByContent verb indicates that the specified
entity is retrieved by its non-key values. The verb operation returns a
business object that contains the current values for the application
entity.
- For a
hierarchical business object, the RetrieveByContent verb indicates that one or
more application entities (to match the entire business object) are retrieved
by the non-key values of the top-level business object. The verb
operation returns a business object in which all simple attributes of each
business object in the hierarchy match the values of the corresponding entity
attributes, and the number of individual business objects in each child
business object array matches the number of child entities in the
application.
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.
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.
The RetrieveByContent operation should return one of the outcome-status
values shown in Table 36.
Table 36. 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.
