TO BE DISCUSSED
I find it really hard to justify that FullTextQuery extends the Hibernate ORM Query type, given that many methods do not make sense in the context of Hibernate Search.
These methods in particular do not make any sense:
Those currently throw exceptions because we can't implement them (yet):
- javax.persistence.Query#setParameter(javax.persistence.Parameter<T>, T) and related
- javax.persistence.Query#setLockMode and related
And those seem to work, but actually don't have any effect :
- javax.persistence.Query#setFlushMode and related
- org.hibernate.query.Query#applyGraph and related
- org.hibernate.query.Query#setCacheMode, org.hibernate.query.Query#setCacheRegion and related
The problem is less pronounced for FullTextSession, but it's still hard to find a good reason for it to extend Session; composition (FullTextSession.getSession() returning the ORM Session) would work just as well.
Even on the maintenance side, this inheritance causes a significant burden: for queries in particular, many methods will not work unless we take explicit steps to wire them appropriately, or even cannot work at all (we have to override them to throw an UnsupportedOperationException. But we extend an abstract class from ORM, which provides an implementation for many such methods (though the implementation is often inappropriate in the context of Search). Thus many problems are never detected, and users will be able to use these methods but they won't produce the expected effects.
At the very least, I would be in favor of using our own types as the primary representation of these objects, and just provide adaptors accessible through some toORM or toJPA methods, with the appropriate warnings on these methods ("some methods on the adaptor may not be implemented appropriately, only the main ones are"). Then the users that really need to use the ORM/JPA interfaces would do so explicitly, with full knowledge of the limitations.
We could also consider removing adaptors completely, but I suspect query adaptors are useful to some users, in particular when integrating with other frameworks.