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 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."Sending the verb-processing response" on page
179.
