You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by mt...@apache.org on 2010/02/14 13:43:51 UTC
svn commit: r910003 - in /openjpa/trunk/openjpa-project/src/doc/manual:
jpa_overview_query.xml jpa_tutorials.xml openjpa_legal.xml
ref_guide_conf.xml ref_guide_dbsetup.xml ref_guide_mapping.xml
ref_guide_optimization.xml supported_databases.xml
Author: mtylenda
Date: Sun Feb 14 12:43:46 2010
New Revision: 910003
URL: http://svn.apache.org/viewvc?rev=910003&view=rev
Log:
OPENJPA-1510: User manual corrections: some terms made consistent in case, made hint and locking descriptions more database-agnostic, removed an old MySQL known issue, H2 version updated.
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml
openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml
openjpa/trunk/openjpa-project/src/doc/manual/openjpa_legal.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml
Modified: openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml?rev=910003&r1=910002&r2=910003&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_query.xml Sun Feb 14 12:43:46 2010
@@ -737,8 +737,12 @@
Query Hints
</title>
<para>
-JPQL provides support for hints which are name/value pairs used to control locking and optimization keywords in sql.
-The following example shows how to use the JPA hint api to set the <classname>ReadLockMode</classname> and <classname>ResultCount</classname> in the OpenJPA fetch plan. This will result in the sql keywords OPTIMIZE FOR 2 ROWS and FOR UPDATE to be emitted into the sql provided that a pessimistic LockManager is being used.
+JPQL provides support for hints which are name/value pairs used to control locking and optimization keywords in SQL.
+The following example shows how to use the JPA hint API to set the <classname>ReadLockMode</classname>
+and <classname>ResultCount</classname> in the OpenJPA fetch plan. This will result in
+a database-specific SQL keyword (usually FOR UPDATE) to be emitted into the SQL provided that a
+pessimistic LockManager is being used. Additionally, if a DB2 database is being used,
+the OPTIMIZE FOR 2 ROWS clause will also be emitted.
</para>
<example id="jpa_query_hint1">
<title>
@@ -761,10 +765,13 @@
Locking Hints
</title>
<para>
-To avoid deadlock and optimistic update exceptions among multiple updaters, use a pessimistic LockManager, specified in the persistence unit definition, and use a hint name of "openjpa.FetchPlan.ReadLockMode" on queries for entities that must be locked for serialization. The value of <classname>ReadLockMode</classname> can be either "READ" or "WRITE". This results in FOR UPDATE or USE AND KEEP UPDATE LOCKS in sql.
+To avoid deadlock and optimistic update exceptions among multiple updaters, use a pessimistic LockManager, specified in the persistence unit definition,
+and use a hint name of "openjpa.FetchPlan.ReadLockMode" on queries for entities that must be locked for serialization.
+The value of <classname>ReadLockMode</classname> can be either "READ" or "WRITE".
+This results in a database-specific locking keyword (usually FOR UPDATE) to be emitted into the SQL.
</para>
<para>
-Using a <classname>ReadLockMode</classname> hint with JPA optimistic locking ( i.e. specifying LockManager = "version") will result in the entity version field either being reread at end of transaction in the case of a value of "READ" or the version field updated at end of transaction in the case of "WRITE". You must define a version field in the entity mapping when using a version LockManager and using ReadLockMode.
+Using a <classname>ReadLockMode</classname> hint with JPA optimistic locking (i.e. specifying LockManager = "version") will result in the entity version field either being reread at end of transaction in the case of a value of "READ" or the version field updated at end of transaction in the case of "WRITE". You must define a version field in the entity mapping when using a version LockManager and using ReadLockMode.
</para>
<table>
<title>
@@ -793,9 +800,9 @@
READ
</entry>
<entry colname="pessimistic">
- sql with UPDATE
+ SQL with FOR UPDATE
</entry>
- <entry colname="version">sql without update;
+ <entry colname="version">SQL without FOR UPDATE;
<para>
reread version field at the end of transaction and check for no change.
</para>
@@ -806,10 +813,10 @@
WRITE
</entry>
<entry colname="pessimistic">
- sql with UPDATE
+ SQL with FOR UPDATE
</entry>
<entry colname="version">
- sql without update;
+ SQL without FOR UPDATE;
<para>
force update version field at the end of transaction
</para>
@@ -820,10 +827,10 @@
not specified
</entry>
<entry colname="pessimistic">
- sql without update
+ SQL without FOR UPDATE
</entry>
<entry colname="version">
- sql without update
+ SQL without FOR UPDATE
</entry>
</row>
</tbody>
@@ -857,7 +864,7 @@
Result Set Size Hint
</title>
<para>
-To specify a result set size hint to those databases that support it, specify a hint name of "openjpa.hint.OptimizeResultCount" with an integer value greater than zero. This causes the sql keyword OPTIMIZE FOR to be generated.
+To specify a result set size hint to those databases that support it, specify a hint name of "openjpa.hint.OptimizeResultCount" with an integer value greater than zero. This causes the SQL keyword OPTIMIZE FOR to be generated.
</para>
</section>
<section id="jpa_hints_isolation">
@@ -865,7 +872,7 @@
Isolation Level Hint
</title>
<para>
-To specify an isolation level, specify a hint name of "openjpa.FetchPlan.Isolation". The value will be used to specify isolation level using the sql WITH <isolation> clause for those databases that support it. This hint only works in conjunction with the ReadLockMode hint.
+To specify an isolation level, specify a hint name of "openjpa.FetchPlan.Isolation". The value will be used to specify isolation level using the SQL WITH <isolation> clause for those databases that support it. This hint only works in conjunction with the ReadLockMode hint.
</para>
</section>
<section id="jpa_hints_fetchplan">
@@ -884,7 +891,7 @@
<para>
The hint names "openjpa.hint.MySQLSelectHint" and
"openjpa.hint.OracleSelectHint" can be used to specify a string value
-of a query hint that will be inserted into sql for MySQL and Oracle databases.
+of a query hint that will be inserted into SQL for MySQL and Oracle databases.
See <xref linkend="dbsupport_mysql_query_hints"/> and
<xref linkend="dbsupport_oracle_query_hints"/> for examples.
</para>
@@ -903,9 +910,12 @@
<programlisting>
...
@NamedQuery(name="magsOverPrice",
-query="SELECT x FROM Magazine x WHERE x.price > ?1",
-hints={ @QueryHint (name="openjpa.hint.OptimizeResultCount", value="2"),
- @QueryHint (name="openjpa.FetchPlan.ReadLockMode",value="WRITE")} )
+ query="SELECT x FROM Magazine x WHERE x.price > ?1",
+ hints={
+ @QueryHint(name="openjpa.hint.OptimizeResultCount", value="2"),
+ @QueryHint(name="openjpa.FetchPlan.ReadLockMode", value="WRITE")
+ }
+)
...
</programlisting>
</example>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml?rev=910003&r1=910002&r2=910003&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml Sun Feb 14 12:43:46 2010
@@ -382,7 +382,7 @@
javac *.java
</programlisting>
<para>
-You can use any java compiler instead of <command>javac</command>.
+You can use any Java compiler instead of <command>javac</command>.
</para>
</listitem>
<listitem>
@@ -1158,8 +1158,8 @@
</classname> class, looking for all snakes named Killer and providing a detailed
listing of them. The second is rabbit-centric - it examines the rabbits in the
database for instances whose <literal>eater</literal> is named Killer. This
-second query demonstrates the that simple java 'dot' syntax is used when
-traversing an to-one field in a query.
+second query demonstrates that the simple Java 'dot' syntax is used when
+traversing a to-one field in a query.
</para>
<para>
It is also possible to traverse collection fields. Imagine that there was a
Modified: openjpa/trunk/openjpa-project/src/doc/manual/openjpa_legal.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/openjpa_legal.xml?rev=910003&r1=910002&r2=910003&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/openjpa_legal.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/openjpa_legal.xml Sun Feb 14 12:43:46 2010
@@ -74,7 +74,7 @@
Apache Commons Pool project
</para></listitem>
<listitem><para>
- Apache Geronimo project (JMS 1.1, JTA 1.1 and JPA 2.0 spec apis)
+ Apache Geronimo project (JMS 1.1, JTA 1.1 and JPA 2.0 spec APIs)
</para></listitem>
<listitem><para>
JCP JSR-317 JPA 2.0 Schemas
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=910003&r1=910002&r2=910003&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 Sun Feb 14 12:43:46 2010
@@ -2075,7 +2075,6 @@
</para>
</section>
-InitializeEagerly
<section id="openjpa.InitializeEagerly">
<title>
openjpa.InitializeEagerly
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml?rev=910003&r1=910002&r2=910003&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml Sun Feb 14 12:43:46 2010
@@ -664,10 +664,10 @@
<para>
<indexterm>
<primary>
- SQLServer
+ SQL Server
</primary>
</indexterm>
-<literal>sqlserver</literal>: Dictionary for Microsoft's SQLServer database.
+<literal>sqlserver</literal>: Dictionary for Microsoft's SQL Server database.
This is an alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/SQLServerDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.SQLServerDictionary</classname></ulink>
@@ -3962,12 +3962,12 @@
<literal>always</literal>: Each <classname>EntityManager</classname> obtains a
single connection and uses it until the <classname>EntityManager</classname>
closes. Great care should be taken when using this property if the application
-cannot close the EntityManager (ie container-managed EntityManagers in a JEE
+cannot close the EntityManager (i.e. container-managed EntityManagers in a JEE
Application Server). In this case the connection will remain open for an
undefined time and the application may not be able to recover from a terminated
-connection(ie if a TCP/IP timeout severs the connection to the database).
+connection (for example, if a TCP/IP timeout severs the connection to the database).
For this reason the <literal>always</literal> option should not be used with
-container managed EntityManagers.
+container-managed EntityManagers.
</para>
</listitem>
<listitem>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml?rev=910003&r1=910002&r2=910003&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_mapping.xml Sun Feb 14 12:43:46 2010
@@ -549,7 +549,7 @@
<para>
<literal>-annotations/-ann <true/t | false/f></literal>: Set to
<literal>true</literal> to
-generate JPA annotations in generated java classes.
+generate JPA annotations in generated Java classes.
</para>
</listitem>
<listitem>
@@ -652,7 +652,7 @@
schema. The format is <literal> SQLTYPE1=JavaClass1,SQLTYPE2=JavaClass2
</literal>. The SQL type name first looks for a customization based on <literal>
SQLTYPE(SIZE,PRECISION)</literal>, then <literal>SQLTYPE(SIZE)</literal>, then
-<literal>SQLTYPE(SIZE,PRECISION)</literal>. So if a column whose type name is
+<literal>SQLTYPE</literal>. So if a column whose type name is
<literal>CHAR</literal> is found, it will first look for the <literal>
CHAR(50,0)</literal> type name specification, then it will look for <literal>
CHAR(50)</literal>, and finally it will just look for <literal>CHAR</literal>.
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml?rev=910003&r1=910002&r2=910003&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml Sun Feb 14 12:43:46 2010
@@ -461,9 +461,9 @@
</para>
</entry>
<entry colname="desc">
-If you have enabled scrollable result sets and on-demand loading but do you not
+If you have enabled scrollable result sets and on-demand loading but you do not
require it, consider disabling it again. Some JDBC drivers and databases
-(SQLServer for example) are much slower when used with scrolling result sets.
+(SQL Server for example) are much slower when used with scrolling result sets.
</entry>
</row>
<row>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml
URL: http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml?rev=910003&r1=910002&r2=910003&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/supported_databases.xml Sun Feb 14 12:43:46 2010
@@ -320,13 +320,13 @@
<link linkend="dbsupport_h2">H2 Database Engine</link>
</entry>
<entry colname="dbversion">
- 1.0
+ 1.1.118
</entry>
<entry colname="drivname">
H2
</entry>
<entry colname="drivversion">
- 1.0
+ 1.1.118
</entry>
</row>
<row>
@@ -1050,13 +1050,6 @@
</listitem>
<listitem>
<para>
-Some version of the MySQL JDBC driver have a bug that prevents OpenJPA from
-being able to interrogate the database for foreign keys. Version 3.0.14 (or
-higher) of the MySQL driver is required in order to get around this bug.
- </para>
- </listitem>
- <listitem>
- <para>
When using large result sets with MySQL there are a number of documented limitations.
Please read the section titled "ResultSet" in the "MySQL JDBC API Implementation Notes".
The net effect of these limitations is that you will have to read all of the rows of a