Automic Development provided a response. I will paraphrase it here.
The AE DB Load program (ucybdbld) loads objects in a single database transaction. When the ucybdbld program exits with return code 0, this means all of the objects were successfully loaded into the target AE system. Work processes, including the DWPs that handle Java API requests, maintain an object cache that is used to process SearchObject
operations. When the DB Load program loadss objects it notifies the WPs that they need to refresh their caches. It does so by adding entries to the internal task list (ITL) table. If a SearchObject request is processed between the the DB Load and the refresh of the object cache, the results may be incomplete or incorrect.
Error-prone approach
- Run the DB load.ucybdbld loads objects & writes corresponding entries to ITL table.
- Run the SearchObject request.
This approach is error-prone, because the following two steps may execute either before or after the SearchObject request is handled:
- DWP checks for & finds entries in the ITL table.
- DWP updates its object cache & removes entries from the ITL table.
If you’re lucky, it will run like this:
- Run the DB load.ucybdbld loads objects & writes corresponding entries to ITL table.
- DWP checks for & finds entries in the ITL table.
- DWP updates its object cache & removes entries from the ITL table.
- Run the SearchObject request.
However, if you’re unlucky, it will run like this:
- Run the DB load.ucybdbld loads objects & writes corresponding entries to ITL table.
- Run the SearchObject request.
- DWP checks for & finds entries in the ITL table.
- DWP updates its object cache & removes entries from the ITL table.
To ensure that the DWPs have an up-to-date object cache when the SearchObject request is sent, it is necessary to insert an extra step in the process.
More reliable approach
- Run the DB load program, loading objects & writing corresponding entries to ITL table.
- Check the ITL table for entries. If the table contains any entries, wait a few seconds and try again. Wait until the table is empty. This ensures that the following steps have been completed:
- DWP checks for & finds entries in the ITL table.
- DWP updates its object cache & removes entries from the ITL table.
- Once the ITL table is empty, Run the SearchObject request.
Automic confirmed that because of the design of the AE, there is no way to guarantee correct results from SearchObject using the Java APIs alone. It is necessary to insert this additional step that performs a direct query of the AE DB. In very busy systems, where multiple DB loads may run simultaneously or in quick succession, it is conceivable that another DB load is run between the ITL check and the execution of SearchObject. So really, there is no 100% foolproof way to guarantee correct results from SearchObject.
However, in most cases, as long as SearchObject is executed quickly after the ITL check, it should return correct results. Preventing multiple simultaneous DB loads, and better yet, adding a delay between DB loads, will also help mitigate the problem. (See also this discussion: Poor AE performance following DB load of transport case.)
This problem raises the more general topic of API completeness & reliability. To get some clarity on the topic, I have posed these questions to Automic:
- What API operations may not always return correct results?
- In which circumstances are these APIs likely to return incorrect results?
- What steps can be taken to mitigate this?
I will post an update here when I have answers to these questions.