Development information
Query API
Getting the results
This document gives an overview of how the results of a query are generated and passed back to the client application.
See also
The Query interface doesn't specify how the results should be returned.
It is up to the implementors to add methods for that. In the current implementation
we have used two strategies. Return the result as a list or as an iterator,
using either the list() or iterate() methods. The
list() method is not available for queries that has a potential for
returning large result sets, ie. DataQuery and DynamicQuery.
In both cases there is the option of getting the total count of items from
the QueryResult.getTotalCount(). Here, the total count means the
number of items that would have been returned if not any limits to the query had
been specified with Query.setFirstResult() and/or
Query.setMaxResults(). The option Query.setReturnTotalCount()
must also be enabled.
The only actual implementation is or a ResultList is the
ItemResultList class. Here, the AbstractResultList
class provides an implements of all methods that modify the list. Since that is
not allowed it always throws an UnsupportedOperationException.
An ItemResultList is created by an ItemQuery
when the ItemQuery.list() method is called. This method
first builds the HQL from the superclass
(AbstractEntityQuery.getMainHqlQuery()) and enables any runtime
filters (see the Query API overview). It then
passes the query on to HibernateUtil.loadList() which returns
the result in a list object.
The result list of course contains data layer objects since that is all Hibernate
knows about. This list is passed to a new instance of ItemResultList,
which is returned back to the client application. The data layer objects are only
converted to item objects when the client requests them with, for example, the
List.get() method.
The ResultIterator has two implementations (not including the
dynamic part): ItemResultIterator and DataResultIterator.
The only difference is that the former is returning item objects while the latter
is returning data layer objects.
The iterators are created by either the ItemQuery.iterate() or
the DataQuery.iterate() method. Both of these methods builds
the query in the same way as the ItemQuery.list method, but
uses the HibernateUtil.loadIterator() method instead.
Hibernate returns the results as a org.hibernate.ScrollableResults
object, which is too complex for our needs. The ScrollIterator
provides a java.util.Iterator view of the ScrollableResults
object.
Just as for the list implementation the two iterator implementations only
contains the data layer objects. The ItemResultIterator
converts the data layer objects to item objects when the next()
method is called. The DataResultIterator doesn't have to do
that but must evict the object from the Hibernate session that loaded it,
or it would be possible for a user to bypass the write permission checks.
Read more about this in the Dynamic API overview.