[Hibernate] iterator docs

[Anton v. S. <an...@ap...>]

Gavin,

Not that this will necessarily forestall all newbie questions about it, but
I think the Javadoc for iterator() could be more explicit.  It currently
says:

"Execute a query and return the results in an iterator. Results are lazily
instantiated. Write the given value to "?" in the query string.  iterate()
is usually a less efficient way to retrieve objects than find()."

A user might be forgiven for assuming that "lazily instantiated" means that
objects are instantiated lazily, when requested, from a single resultset for
the entire query.  The docs in "6.3 Querying the database" explain this
better.  Perhaps the last sentence above could be replaced with something
like this:

"The iterator returned by iterate() will issue a separate database query for
each object that is requested, except for objects that are already loaded
and cached in the session.  In many situations, it is more efficient to use
find()."

Adjust to reflect reality... :)

Anton