Hi Pinaki, Was the QuerySQLCache always in the openjpa.jdbc.* configuration? Or, did it get moved from the openjpa.* package? Maybe you are just correcting the documentation (and code) to be consistent, but I can't tell without more digging. My concern is that we can't just move the location of a configuration option without some migration issues. Hopefully, this is just a cleanup exercise.
Thanks, Kevin On Thu, Feb 5, 2009 at 2:06 PM, <[email protected]> wrote: > Author: ppoddar > Date: Thu Feb 5 20:06:02 2009 > New Revision: 741275 > > URL: http://svn.apache.org/viewvc?rev=741275&view=rev > Log: > OPENJPA-703: Update Prepared Query Cache documentation. > > Modified: > > > openjpa/trunk/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/conf/JDBCConfigurationImpl.java > > > openjpa/trunk/openjpa-persistence-jdbc/src/test/java/org/apache/openjpa/persistence/jdbc/sqlcache/TestPreparedQueryCache.java > openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml > openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml > > Modified: > openjpa/trunk/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/conf/JDBCConfigurationImpl.java > URL: > http://svn.apache.org/viewvc/openjpa/trunk/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/conf/JDBCConfigurationImpl.java?rev=741275&r1=741274&r2=741275&view=diff > > ============================================================================== > --- > openjpa/trunk/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/conf/JDBCConfigurationImpl.java > (original) > +++ > openjpa/trunk/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/conf/JDBCConfigurationImpl.java > Thu Feb 5 20:06:02 2009 > @@ -305,7 +305,7 @@ > // This plug-in is declared in superclass but defined here > // because PreparedQueryCache is currently available for JDBC > // backend only > - preparedQueryCachePlugin = addPlugin("QuerySQLCache", true); > + preparedQueryCachePlugin = addPlugin("jdbc.QuerySQLCache", true); > aliases = new String[] { > "true", > "org.apache.openjpa.jdbc.kernel.PreparedQueryCacheImpl", > "false", null > > Modified: > openjpa/trunk/openjpa-persistence-jdbc/src/test/java/org/apache/openjpa/persistence/jdbc/sqlcache/TestPreparedQueryCache.java > URL: > http://svn.apache.org/viewvc/openjpa/trunk/openjpa-persistence-jdbc/src/test/java/org/apache/openjpa/persistence/jdbc/sqlcache/TestPreparedQueryCache.java?rev=741275&r1=741274&r2=741275&view=diff > > ============================================================================== > --- > openjpa/trunk/openjpa-persistence-jdbc/src/test/java/org/apache/openjpa/persistence/jdbc/sqlcache/TestPreparedQueryCache.java > (original) > +++ > openjpa/trunk/openjpa-persistence-jdbc/src/test/java/org/apache/openjpa/persistence/jdbc/sqlcache/TestPreparedQueryCache.java > Thu Feb 5 20:06:02 2009 > @@ -73,7 +73,7 @@ > public void setUp() throws Exception { > super.setUp(CLEAR_TABLES, Company.class, Department.class, > Employee.class, Address.class, > - "openjpa.QuerySQLCache", > + "openjpa.jdbc.QuerySQLCache", > "true(excludes='select count(p) from Company > p;select count(p) from Department p')"); > createTestData(); > } > > Modified: > openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml > URL: > http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml?rev=741275&r1=741274&r2=741275&view=diff > > ============================================================================== > --- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml > (original) > +++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_caching.xml Thu > Feb 5 20:06:02 2009 > @@ -1022,48 +1022,83 @@ > </tbody> > </tgroup> > </table> > - </section> > + </section> > + > <section id="ref_guide_cache_querysql"> > - <title> > - Query SQL Cache > - </title> > + <title>Prepared SQL Cache</title> > <indexterm zone="ref_guide_cache_querysql"> > - <primary> > - caching > - </primary> > - <secondary> > - query sql cache > - </secondary> > + <primary>caching</primary> > + <secondary>query sql cache</secondary> > </indexterm> > -<para> > -The Query SQL Cache caches SQL statements corresponding to JPQL queries. > + <para> > +Prepared SQL Cache caches SQL statements corresponding to JPQL queries. > If a JPQL query is executed more than once in the same or different > persistence > -context, the SQL statement generated during the first execution is cached > and > +contexts, the SQL statement generated during the first execution is cached > and > executed directly for subsequent execution. Direct execution of SQL offers > significant performance gain as it saves the cost of parsing query string > and, > more importantly, populating the query expression tree during every > execution. > +Relative performance gain becomes higher as the complexity of forming a > SQL > +query from a JPQL string increases. For example, a JPQL query > <code>Q1</code> > +that involves multiple joins across tables takes more computation to > translate > +into a SQL statement than a JPQL query <code>Q2</code> to select by simple > +primary key identifier. Correspondingly, repeated execution of > <code>Q1</code> > +will gain more performance advantage than <code>Q2</code> with Prepared > SQL > +Cache. > </para> > <para> > -The Query SQL Cache is configured by the <link > linkend="openjpa.jdbc.QuerySQLCache"> > -<literal>openjpa.QuerySQLCache</literal></link> configuration property. > This > +Prepared SQL Cache is configured by the <link > linkend="openjpa.jdbc.QuerySQLCache"> > +<literal>openjpa.jdbc.QuerySQLCache</literal></link> configuration > property. This > property accepts a a plugin string (see <xref > linkend="ref_guide_conf_plugins"/>) > -with value of <literal>true</literal> or <literal>false</literal>. > +with value of <literal>true</literal> or <literal>false</literal>. The > default > +is <literal>true</literal>. > </para> > <para> > -Depending upon the mapping of your persistent domain object model, > -lazy/eager fetch settings on the relation paths and fetch configuration, a > -single JPQL may result in multiple SQL statements. If a JPQL query > requires > -more than one SQL statement to be executed, then the JPQL query is not > cached. > -The other critical point to remember while using the Query SQL Cache is > that > -change in fetch plan or locking mode may cause a different target SQL > statement > -than the original. But Query SQL Cache does not track such changes and > reuses > -the cached SQL under the assumption that the query execution context has > -remained unchanged. > +Following salient points to be noted regarding usage of Prepared Query > Cache. > +<itemizedlist> > + <listitem> > + Prepared Query Cache uses the original JPQL string as the key to > index the > + corresponding SQL statement. Hence the JPQL strings that are > semantically > + identical but differ by character case or identification variables > are > + considered as different by this cache. > + </listitem> > + <listitem> > + A JPQL query may not always translate into a > <emphasis>single</emphasis> > + SQL query. The JPQL queries that require multiple select statements > are > + never cached. > + </listitem> > + <listitem> > + Same JPQL query may result into different SQL statements under > different > + execution context. Execution context parameters such as fetch > configuration > + or locking mode determine the resultant SQL. However, Prepared SQL > Cache > + <emphasis>does not</emphasis> capture the execution context > parameters > + while caching a generated SQL. > + </listitem> > + <listitem> > + The named or positional parameters of a JPQL query can be set to > different > + values across executions. In general, the corresponding cached SQL > statement > + will be re-parameterized accordingly. However, the parameter value > itself can > + determine the SQL query. For example, when a JPQL query compares a > relation > + field for equality against a parameter <code>p</code>, whether the > actual > + value of <code>p</code> is <code>null</code> or not will determine > the > + generated SQL statement. Another example is collection valued > parameter for > + <code>IN</code> expression. Each element of a collection valued > parameter > + results into a SQL parameter. If a collection valued parameter > across > + executions are set to different number of elements, then the > parameters of > + the cached SQL do not correspond. If such situations are > encountered while > + re-parameterizing the cached SQL, the cached version is not reused > and the > + original JPQL query is used to generate a new SQL statement for > execution. > + </listitem> > + <listitem> > + JPQL query that returns a <emphasis>numeric</emphasis> value such > as > + <code>SELECT count(p) FROM PObject p</code> is never cached. > + </listitem> > +</itemizedlist> > </para> > <para> > -Several mechanisms are available to the application to deactivate SQL > cacheing > -for a query. > - <listitem>A user application can deactivate SQL Query Cache > +Several mechanisms are available to the application to bypass SQL caching > +for a JPQL query. > +<itemizedlist> > + <listitem>A user application can disable Prepared SQL Cache > for entire lifetime of a persistence context by invoking the > following > method on OpenJPA's EntityMananger interface: > <programlisting> > @@ -1071,11 +1106,11 @@ > </programlisting> > </listitem> > <listitem> > - A user application can instruct a particular execution of a JPQL > query to > + A user application can instruct particular execution of a JPQL > query to > ignore any cached SQL query, by setting > <literal>QueryHints.HINT_IGNORE_PREPARED_QUERY</literal> or > <literal>"openjpa.hint.IgnorePreparedQuery"</literal> to > <literal>true</literal> > - via standard <literal>javax.persistence.Query.setHints()</literal>. > If a > + via standard <literal>javax.persistence.Query.setHint(String, > Object)</literal> method. If a > SQL query has been cached corresponding to the JPQL query prior to > this > execution, then the cached SQL remains in the cache and will be > reused > for any subsequent execution of the same JPQL query. > @@ -1085,10 +1120,19 @@ > ignore any cached SQL query, by setting > <literal>QueryHints.HINT_INVALIDATE_PREPARED_QUERY</literal> or > <literal>"openjpa.hint.InvalidatePreparedQuery"</literal> to > <literal>true</literal> > - The SQL query is removed from the cache and the JPQL query will > never be > - cached again during the lifetime of the entire persistence unit > i.e. > - EntityManagerFactory. > + The SQL query is removed from the cache. Also the JPQL query will > never be > + cached again during the lifetime of the entire persistence unit. > + </listitem> > + <listitem> > + Plug-in property <literal>openjpa.jdbc.QuerySQLCache</literal> can > be > + configured to exclude certain JPQL queries as shown below. > + <programlisting> > + <property name="openjpa.jdbc.QuerySQLCache" > value="true(excludes='select c from Company c;select d from Department > d')"/> > + </programlisting> > + will never cache JPQL queries <code>select c from Company c</code> > and > + <code>select d from Department d</code>. > </listitem> > + </itemizedlist> > </para> > > </section> > > Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml > URL: > http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml?rev=741275&r1=741274&r2=741275&view=diff > > ============================================================================== > --- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml > (original) > +++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml Thu Feb > 5 20:06:02 2009 > @@ -3516,7 +3516,8 @@ > <classname>org.apache.openjpa.meta.MetaDataFactory</classname></ulink> to > use to > store and retrieve object-relational mapping information for your > persistent > classes. See <xref linkend="ref_guide_mapping_factory"/> for details. > - </para> > + </para> > + > </section> > <section id="openjpa.jdbc.QuerySQLCache"> > <title> > @@ -3524,7 +3525,7 @@ > </title> > <indexterm zone="openjpa.jdbc.QuerySQLCache"> > <primary> > - QuerySQLCache > + Prepared SQL Cache > </primary> > </indexterm> > <indexterm zone="openjpa.jdbc.QuerySQLCache"> > @@ -3548,10 +3549,9 @@ > </para> > <para> > <emphasis role="bold">Description:</emphasis> A plugin string (see > -<xref linkend="ref_guide_conf_plugins"/>) describing the > -<classname>java.util.Map</classname> to use for caching of the SQL string > -used by the find operation. See <xref > linkend="ref_guide_cache_querysql"/> for > -details. > +<xref linkend="ref_guide_conf_plugins"/>) describing the options to cache > and > +reuse SQL statements generated for JPQL queries. > +See <xref linkend="ref_guide_cache_querysql"/> for details. > </para> > </section> > <section id="openjpa.jdbc.ResultSetType"> > > >
