openjpa-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pinaki Poddar <>
Subject Re: What happens with invalid query hints?
Date Thu, 03 Dec 2009 18:25:27 GMT

Craig is right.

OpenJPA categories a hint key in the following categories (from JavaDoc on
 *  1. Supported: A key is known to this receiver as collected from
 *     parts of the system. The value of a supported key is recorded and 
 *     available via {@link #getHints()} method. 
 *  2. Recognized: A key is not known to this receiver but has a prefix
 *     is known to this receiver. The value of a recognized key is not
 *     but its value is available via {@link
 *  3. Unrecognized: A key is neither supported nor recognized. The value of
 *     unrecognized key is neither recorded nor set anywhere.

Semantically, this categorization aligns with Craig's classification as 
Craig's category 1 = Supported
Craig's category 2 = Unrecognized
Craig's category 3 = Recognized

The runtime exception handling behavior is somewhat more lenient than what
Craig describes. None of the three categories of hint key raises an
exception. Recognized key is not recorded i.e. they do not appear in
getHints() list. They only generate a warning message. The only exception
scenario is a Supported key supplied with an incompatiable value.

Craig L Russell wrote:
> The specification offers this explanation (3.8.9 in the draft  
> specification dated 2009-10-06):
> Vendors are permitted to support the use of additional, vendor- 
> specific locking hints.  Vendor-specific
> hints must not use the javax.persistence namespace. Vendor-specific  
> hints must be ignored if
> they are not understood.
> So the model is that there are three categories of hints:
> 1. hints that are known to OpenJPA, which are hints defined by the  
> standard plus the hints that are defined by OpenJPA to extend the  
> standard hints. These hints are defined in the OpenJPA name space  
> "openjpa.hint.*" or in the standard hint name space  
> "javax.persistence.*"
> 2. hints that are defined by other vendors in their own name space.
> 3. hints that are in the OpenJPA name space but are not known to  
> OpenJPA. These are usually typos by the user. For example,  
> "openjpa.hint.OOptimizeResultCount".
> Category 1 hints are honored if possible (e.g. the database in use  
> supports the hint).
> Category 2 hints are ignored by OpenJPA. This allows you to use the  
> same set of hints in a program with different persistence vendors.
> Category 3 hints result in an exception. Typos should be caught and  
> reported.
> Sometimes we developers assume that users read and understand the  
> specification along with the OpenJPA user documentation. Bad assumption.
> By the way, this model for hints follows the general model for  
> properties in several JCP specifications.
> Craig
> On Dec 2, 2009, at 3:55 PM, Kevin Sutter wrote:
>> :-)  Yeah, that's kind of confusing, isn't it?  I'm assuming that it  
>> should
>> read as follows:
>> "Hints which can not be processed by a particular database are  
>> ignored.
>> Otherwise, invalid hints will result in an ArgumentException being  
>> thrown."
>> OpenJPA has defined certain hints (and JPA 2.0 has defined some some  
>> hints)
>> that could be used with Queries.  Some of these hints do not apply  
>> to all
>> databases.  So, if you try using one of the hints, for example
>> openjpa.hint.OptimizeResultCount and your designated database  
>> doesn't have
>> the capability to provide the necessary processing for this request,  
>> then it
>> would be ignored.
>> Otherwise, if you pass in a hint that OpenJPA knows nothing about  
>> (let's
>> just say openjpa.hint.FailFast), then you would receive an
>> ArgumentException.  The curious thing here is that this seems to  
>> contradict
>> the hint processing as defined by JPA 2.0.  I believe invalid hints  
>> are
>> supposed to be ignored to allow for programming model compatibilities
>> between JPA providers.  So, maybe there's some clean up necessary in  
>> our
>> documentation.
>> Does this help?  We should probably open a JIRA to address this
>> documentation hiccup.  If you don't have access to open a JIRA, then  
>> let me
>> know and I can open one.
>> Thanks,
>> Kevin
>> On Wed, Dec 2, 2009 at 2:36 PM, KARR, DAVID (ATTCINW)  
>> <>wrote:
>>> I'm just reading through the docs (1.2.1) right now, and I noticed  
>>> the
>>> following statement in section 10.1.7,  "Query Hints":
>>> "Invalid hints or hints which can not be processed by a particular
>>> database are ignored. Otherwise, invalid hints will result in an
>>> ArgumentException being thrown."
>>> I'm a little confused by this.  Under what circumstances will a  
>>> hint be
>>> ignored, and when will it get an ArgumentException?
> Craig L Russell
> Architect, Sun Java Enterprise System
> 408 276-5638
> P.S. A good JDO? O, Gasp!

View this message in context:
Sent from the OpenJPA Users mailing list archive at

View raw message