Apache/openjpa
1
0
Fork 0
mirror of https://github.com/apache/openjpa.git synced 2025-02-26 04:27:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

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.

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/openjpa/trunk@910003 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Milosz Tylenda 2010-02-14 12:43:46 +00:00
parent e70d8bf5f2
commit 8cc89f96dc
8 changed files with 41 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
openjpa-project/src/doc/manual/jpa_overview_query.xml
View File

@ -737,8 +737,12 @@ All input parameters must be single-valued, except in IN expressions
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 @@ Invalid hints or hints which can not be processed by a particular database are i
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 &quot;openjpa.FetchPlan.ReadLockMode&quot; on queries for entities that must be locked for serialization. The value of <classname>ReadLockMode</classname> can be either &quot;READ&quot; or &quot;WRITE&quot;. 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 &quot;openjpa.FetchPlan.ReadLockMode&quot; on queries for entities that must be locked for serialization.
The value of <classname>ReadLockMode</classname> can be either &quot;READ&quot; or &quot;WRITE&quot;.
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 = &quot;version&quot;) will result in the entity version field either being reread at end of transaction in the case of a value of &quot;READ&quot; or the version field updated at end of transaction in the case of &quot;WRITE&quot;. 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 = &quot;version&quot;) will result in the entity version field either being reread at end of transaction in the case of a value of &quot;READ&quot; or the version field updated at end of transaction in the case of &quot;WRITE&quot;. 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 @@ Using a <classname>ReadLockMode</classname> hint with JPA optimistic locking ( i
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 @@ reread version field at the end of transaction and check for no change.
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 @@ force update version field at the end of transaction
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 @@ default behavior.
Result Set Size Hint
</title>
<para>
To specify a result set size hint to those databases that support it, specify a hint name of &quot;openjpa.hint.OptimizeResultCount&quot; 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 &quot;openjpa.hint.OptimizeResultCount&quot; 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 @@ To specify a result set size hint to those databases that support it, specify a
Isolation Level Hint
</title>
<para>
To specify an isolation level, specify a hint name of &quot;openjpa.FetchPlan.Isolation&quot;. The value will be used to specify isolation level using the sql WITH &lt;isolation&gt; 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 &quot;openjpa.FetchPlan.Isolation&quot;. The value will be used to specify isolation level using the SQL WITH &lt;isolation&gt; 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 @@ Any property of an OpenJPA FetchPlan can be changed using a hint by using a nam
<para>
The hint names &quot;openjpa.hint.MySQLSelectHint&quot; and
&quot;openjpa.hint.OracleSelectHint&quot; 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 @@ Hints can also be included as part of a NamedQuery definition.
<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>

6
openjpa-project/src/doc/manual/jpa_tutorials.xml
View File

@ -382,7 +382,7 @@ Compile the <filename>.java</filename> files.
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 @@ The first query is snake-centric - the query runs against the <classname>Snake
</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

2
openjpa-project/src/doc/manual/openjpa_legal.xml
View File

@ -74,7 +74,7 @@ The openjpa-all aggregate JAR includes software developed by the:
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

1
openjpa-project/src/doc/manual/ref_guide_conf.xml
View File

@ -2075,7 +2075,6 @@ or flush before running it against the datastore.
</para>
</section>
InitializeEagerly
<section id="openjpa.InitializeEagerly">
<title>
openjpa.InitializeEagerly

10
openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
View File

@ -664,10 +664,10 @@ class.
<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 @@ property accepts the following values:
<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>

4
openjpa-project/src/doc/manual/ref_guide_mapping.xml
View File

@ -549,7 +549,7 @@ generation.
<para>
<literal>-annotations/-ann &lt;true/t | false/f&gt;</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 @@ the default Java classes to generate for each SQL type that is seen in the
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>.

4
openjpa-project/src/doc/manual/ref_guide_optimization.xml
View File

@ -461,9 +461,9 @@ database only as necessary.
</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>

11
openjpa-project/src/doc/manual/supported_databases.xml
View File

@ -320,13 +320,13 @@ databases that have been fully tested against this release, please refer to the
<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 @@ mismatch between the field that is stored and the field that is retrieved.
</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