Mailing-List: contact users-help@openjpa.apache.org; run by ezmlm
Precedence: bulk
Reply-To: users@openjpa.apache.org
Received-SPF: pass (athena.apache.org: domain of kwsutter@gmail.com designates
 209.85.219.219 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:in-reply-to:references:date:message-id:subject:from:to
         :content-type;
        b=GLQFBtK+Uk1musyq5GX4MsUT+OUal7IgZE89NAQ3KCXDe1I7NfWI+asOBz68Png07I
         C4bcF12eBTbe4ZBHtLVSZxWWZkcEAf4D8UFb1R/dM3/WuJFy81GM5tCzmQ5YMvu+JZst
         UM1LGCN6dZnY3bh7Nr6WHte9lNs5CeraesnYE=
MIME-Version: 1.0
In-Reply-To: <1259864727521-4107811.post@n2.nabble.com>
References: 
 <E0529A8FFC2C9143A5F1BB9A89101D0607838D45@BD01MSXMB018.US.Cingular.Net>
	 <89c0c52c0912021555g225af468s88d1ad34ac8ddbd2@mail.gmail.com>
	 <628AF0CE-164C-4E1E-91EF-0DCBA37B6F00@SUN.com>
	 <1259864727521-4107811.post@n2.nabble.com>
Date: Thu, 3 Dec 2009 13:27:00 -0600
Message-ID: <89c0c52c0912031127i47f418c5re90e7655c9501e72@mail.gmail.com>
Subject: Re: What happens with invalid query hints?
From: Kevin Sutter <kwsutter@gmail.com>
To: users@openjpa.apache.org
Content-Type: multipart/alternative; boundary=00504502d060af06180479d7f959

--00504502d060af06180479d7f959
Content-Type: text/plain; charset=ISO-8859-1

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?

Kevin

On Thu, Dec 3, 2009 at 12:25 PM, Pinaki Poddar <ppoddar@apache.org> 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)
> >> <dk068x@att.com>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:Craig.Russell@sun.com
> > 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.
>

--00504502d060af06180479d7f959--