query-specific flush modes

[gavinking]

While working on #780, I again ran into the mismatch between FlushModeType and its usage patterns with respect to queries.

Let me back up a bit. Historically, that is, before JPA existed, and still today, Hibernate had/has four FlushModes:

• NEVER
• COMMIT
• AUTO
• ALWAYS

The settings AUTO, COMMIT, and NEVER make sense at the session level, in order to control the cost of dirty checking.

On the other hand, ALWAYS and NEVER make sense at the query level, to either:

• force a flush before a native query, or
• skip dirty checking before a given query.

When we wrote the JPA spec, Mike didn't think that NEVER or ALWAYS were necessary, and I didn't object, and so JPA wound up with two flush modes: COMMIT and AUTO. Neither of these make a whole lot of sense as arguments to Query.setFlushMode(), though you can at least use:

query.setFlushMode(COMMIT)

to suppress flushing before a given query.

And, if you need to force a flush before execution of a native query, you can just call flush().

But I would like to be able to specify a flush mode for, e.g. a @NamedNativeQuery or a @NativeReaQuery as part of the annotation, and unfortunately the FlushModeType just doesn't work for that.

We recently added a new QueryFlushMode enum to Hibernate:

/**
 * Enumerates the possible flush modes for execution of a
 * {@link org.hibernate.query.Query}. An explicitly-specified
 * {@linkplain Query#setQueryFlushMode(QueryFlushMode)
 * query-level flush mode} overrides the current
 * {@linkplain org.hibernate.Session#getHibernateFlushMode()
 * flush mode of the session}.
 *
 * ...
 */
public enum QueryFlushMode {
	/**
	 * Flush before executing the query.
	 */
	FLUSH,
	/**
	 * Do not flush before executing the query.
	 */
	NO_FLUSH,
	/**
	 * Let the owning {@linkplain org.hibernate.Session session}
	 * decide whether to flush, depending on its current
	 * {@link org.hibernate.FlushMode}.
	 */
	DEFAULT
}

I think it would be nice to add something very similar to the Persistence spec, after we reach a resolution on #780.

Note that this is a lower-priority issue than other things we're working on right now, so I'm just parking it here.