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

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);

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
}