(DataObjectUtils API below is available since 1.2M10. SingleObjectQuery, a precursor of ObjectIdQuery, was available since 1.2M9. In 1.2M12 SingleObjectQuery was renamed to ObjectIdQuery)
ObjectIdQuery is a query that selects objects matching an ObjectId. Considering that ObjectId must be unique, the result of such query is a single object or no objects.
Normally if you need to find an object that matches a certain primary key value, you would use DataObjectUtils.objectForPK(DataContext,String,int). This method will look up an object in the cache, and only run a query if it is not yet cached. ObjectIdQuery gives the user more control of the object caching behavior. It supports three possible caching policies:
|ObjectIdQuery.CACHE||This policy is similar to DataObjectUtils behavior. If an object is already cached (either at the DataContext or DataDomain level), it is returned, otherwise the fetch is performed.|
|(default policy) ObjectIdQuery.CACHE_REFRESH||This policy forces a database fetch. If an object is already cached (either at the DataContext or DataDomain level), cache is refreshed with a new version and a fresh object is included in the result.|
|ObjectIdQuery.CACHE_NO_REFRESH||This policy suppresses database fetch. If an object is already cached (either at the DataContext or DataDomain level), query returns this object. Otherwise it returns an empty result.|
An example of getting a guranteed fresh object:
An example of checking whether an object is already cached: