> -----Original Message----- > From: Kevin Sutter [mailto:[email protected]] > Sent: Thursday, December 03, 2009 11:27 AM > To: [email protected] > Subject: Re: What happens with invalid query hints? > > Yep, I think we're all in agreement on how we should process these > hints. > But, the point of the original posting was that the documentation > doesn't > explain this very well. So, we still need a JIRA to get this cleaned > up. > Agree?
Although I had volunteered to create the JIRA, now that there's a great deal more information about this, I'd say someone else would be more appropriate for that. > Kevin > > On Thu, Dec 3, 2009 at 12:25 PM, Pinaki Poddar <[email protected]> > wrote: > > > > > Craig is right. > > > > OpenJPA categories a hint key in the following categories (from > JavaDoc on > > HintHandler) > > * 1. Supported: A key is known to this receiver as collected from > > different > > * 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 > > which > > * is known to this receiver. The value of a recognized key is > not > > recorded > > * but its value is available via {...@link > > FetchConfiguration#getHint(String)} > > * 3. Unrecognized: A key is neither supported nor recognized. The > value > > of > > a > > * 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) > > >> <[email protected]>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 http://db.apache.org/jdo > > > 408 276-5638 mailto:[email protected] > > > P.S. A good JDO? O, Gasp! > > > > > > > > > > > > > > > > > > ----- > > Pinaki > > -- > > View this message in context: > > http://n2.nabble.com/What-happens-with-invalid-query-hints- > tp4102163p4107811.html > > Sent from the OpenJPA Users mailing list archive at Nabble.com. > >
