RetrieveAll

RetrieveAll returns a batch of records that match the values provided in the request business object. The records are returned as a collection of business objects through a top-level container business object.

CCI clients of resource adapters that support batch results must be capable of recognizing a top-level container and iterating through the child objects that represent the results of the query. The client can then extract any individual business object in the container and deliver it to the rest of the system as with any single business object. This obviously requires the creation of additional business object container structure definitions by the user or during metadata import for each business object type that the user intends to query in batch. The business object container is shown in the illustration.

Business object container

This approach is favored over that of the JDBC-style ResultSet support as described in the JCA specification. However, if an EIS provides native ResultSet support or if it makes sense then adapter developers are encouraged to implement the CCI ResultSet interfaces to provide customers with a high-performance alternative to the generic batch retrieval approach described in this document.

The container object is produced by the data binding for use in the IBM® Business Process Manager or Websphere Enterprise Service Bus environment. Internally, the adapter will model the multiple retrieved records as a list of top-level records that can be iterated over using the getNext() method of the output Record.

Note: The use of the operation name RetrieveAll rather than RetrieveByContent (as used by the WebSphere® Business Integration adapters) distinguishes this operation as a new and clear standard. Support for RetrieveByContent was inconsistent across previous adapters: some would retrieve a single object and return special error codes if there were more objects that matched while other adapters would create special containers to return multiple values.

Note: The RetrieveAll operation always returns a result set regardless of how many (if any) matches are found.

Processing overview

RetrieveAll processing is as follows:

RetrieveAll should make the adapter ready to return multiple objects. For each of the objects that will be returned, the "getNext()" method will be called. Each call to "getNext" should advance the cursor to the next top-level record.

Note: Adapters should check the property MaxRecords in the WBIInteractionSpec instance to determine the maximum number of records to return in order to avoid out-of-memory issues.

Operation return value

The adapter performs a query and retrieves a result set of all objects that match a given set of values. The output object is a container that holds an 0..n objects of the same type as the input object.

Error handling

RecordNotFoundException is thrown if any populated properties in the input business object do not exist in the EIS.

MatchesExceededLimitException is thrown if the number of hits in the EIS exceeds the value of MaxRecords as defined in the interaction specification. The property MatchCount will contain the actual number of hits that the adapter had in the EIS so that users can either increase their limit or refine their search appropriately.

EISSystemException is thrown if the EIS reports any unrecoverable errors.