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