(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:
| Policy | Cache Behavior |
|---|---|
| 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:
ObjectId id = new ObjectId("Artist", Artist.ARTIST_ID_PK_COLUMN, 55); // this constructor implicitly uses "CACHE_REFRESH" policy, so a fresh object will be returned ObjectIdQuery query = new ObjectIdQuery(id); DataContext context = ... Artist object = (Artist) DataObjectUtils.objectForQuery(context, query);
An example of checking whether an object is already cached:
ObjectId id = new ObjectId("Artist", Artist.ARTIST_ID_PK_COLUMN, 55); ObjectIdQuery query = new ObjectIdQuery(id, false, ObjectIdQuery.CACHE_NO_REFRESH); DataContext context = ... Artist object = (Artist) DataObjectUtils.objectForQuery(context, query); if(object == null) { // not cached } else { // cached }