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